My company has developed several projects. With time, we have found that certain functionalities were implemented more than once in more than one project.
Now we're aiming at extracting the common code into reusable components.
However, we need a tool to work as a cataloge for all reusable components, so that whenever a developer needs to search if a functionality was already implemented into a component, he can search this "reusable components" tool and if found, he can read a quick description of what this component does.
My question is: Are there any free tools out there we can use to document our reusable components?
Thanks...
I think you are looking for a wiki.
For example, take a look at DokuWiki. It's free software. It only needs a server with PHP (no database).
Each snippet/component can be on its own page (markup for code with syntax highlighting available). And you can link all pages. So you'll organize a structure that suits your needs by linking pages.
All users can edit (if you want to allow that) the pages. And you can restrict the access to the wiki (so only your employees can read/edit the wiki).
There are many other wiki softwares, of course.
Yes, there are free tools out there, such as doxygen and Javadoc, which can be used to help in documenting your code and components.
All such tools, though, require assistance from programmers; both the tools I've mentioned require adherence to some discipline in making comments in the code in particular formats. Automatic generation of useful documentation from code which has not been specially annotated is, I confidently assert, well beyond the capabilities of any available (free or costly) documentation tool.
If you edit your question with details of the programming languages and other tools you use you may get more useful answers than this one.
Related
Sourcegraph- this site help me find usage of some of the libraries and usage examples provided by others, where official documentation of the libraries would go only so far. This has been incredibly valuable to me as a developer.
I'd like to see how other developers have used some APIs. We are working on a really huge team. Of course there are all sorts of permissions restrictions for multiple projects. However, most of the code is open. It really is a valuable asset to people like me.
TFS is a source control provider, I think it should also have something inside like sourcegraph. My question is- What's the best way to do this in TFS?
Suggest you to upgrade your TFS to TFS2017. This new release includes our most recent feature innovations and improvements. One of important update is code serach.
Code Search
Code Search provides fast, flexible, and accurate search across all your code. As your codebase expands and is divided across multiple projects and repositories, finding what you need becomes increasingly difficult. To maximize cross-team collaboration and code sharing, Code Search can quickly and efficiently locate relevant information across all your projects.
From discovering examples of an API's implementation, browsing its definition, to searching for error text, Code Search delivers a one-stop solution for all your code exploration and troubleshooting needs.
Code Search offers:
Search across one or more projects
Semantic Ranking
Rich filtering
Code collaboration
For details, see Search across all your code.
Sourcegraph now supports full-regex search across all code and is now deployable as a single Docker image (https://about.sourcegraph.com/docs) and indexes any Git-based code host.
I am willing to build a wiki-based website that would have some other features, namely comments, social sharing, video insertion, article rating and gamification. In a nutshell, something very close to the StackExchange's websites, but the pages would consist of a single piece article instead of a thread of questions implementing the footnote feature.
I have not coded a single line yet.
I am rather experienced with Grails, so I know Groovy and Java. I also know JQuery and a bit of PHP, but I can learn basically everything required. I will be the only one programming on the project.
My questions are:
Which technology should I use according to YOU ?
Should I use Grails as this is what I know best, and try to integrate a wiki technology within my app (if yes, which one) ?
Should I start from an already existing wiki technology (WikiMedia, XWiki, TWiki, Moinmoin, ...) and modify it to integrate the features I need (gamification, comments, video insertion, article rating and social sharing) ? Once again, if you think that is the best solution, please quote a technology, and if possible, tell me why is this THE one.
Thank you very much for your help. I find it rather hard to choose, and ever harder to know which path is the right one to go.
Any suggestion is most welcome.
I would suggest using MediaWiki for the following reasons
You mentioned a wiki-based website
It has lots of extensions built already for your needs (comments, article rating, sharing, comments)
Since you mentioned you know little PHP, you can also modify some of the extensions for your use.
MediaWiki has (via extensions) support for social sharing, video insertion and article rating, and not-great-but-okay support for comments. (Probably most other wiki platforms too - these are common enough features.) Wikia (a MediaWiki-based wiki farm who opensourced most of their custom code) has some gamification features, though I am not familiar with them. Also, MediaWiki has the advantage of having the most widely known wiki dialect (due to the popularity of Wikipedia).
That said, if you are going for minimal developement effort, I would look into adding wiki features to an existing StackOverflow clone before trying to add gamification, comment etc. features to a wiki.
We are looking to initiate a bdd-style approach, inspired by Gojko Adzic's specification by example. Implementation is in java and devs are already writing junit tests.
Key requirement is that specifications (acceptance tests) can be written, read and maintained by non-developers. The project will run as an agile team - so it's fine if devs have to instrument the specs. However, I don't want developers, testers or domain experts having to read or write something that looks like code.
So far I've looked at FitNesse, Concordion and various others (e.g. Spock). I've rejected spock and similar tools because they target developers as the primary audience. FitNesse seems to meet most of the requirements.
Concordion is probably current favourite however: specs looks cleaner and simpler.
So my question (actually three):
Any suggestions for other tools I should look at?
Has anyone been successful with using concordion (or another tool) in this way?
Is concordion still actively developed/supported? Difficult to tell from website and most related SO questions are several years old.
Thanks.
I've worked with a number of teams implementing Specification by Example with Concordion. We train our whole team up to write Concordion specifications in HTML. Only a small subset of HTML is required, so we can train a newbie in about 30 minutes. Typically we have the testers writing the HTML specification, with the BA or Scrum Master sometimes writing them.
We've used Eclipse (Web Page Editor) for editing the HTML. This works well, except that Concordion requires valid XHTML, and Eclipse does not allow HTML to be validated as XHTML. This mostly shows with <br> tags being used rather than <br/>. We cover this off in training. We also train the whole team in the use of source control. By using Eclipse, we have a single user interface for editing and source control. We also find that having the team using the same IDE is a step on the journey to a cross-functional team.
I know of another team where the BA is writing the specifications using a Mac-based HTML editor.
Concordion is actively maintained, with rapid responses on the mailing list (Yahoo) and the issues list. The Concordion codebase is stable. The active development over the last year or so has focussed on the extension mechanism, allowing users to add commands and listeners (eg. for capturing screenshots on test failure).
Also take a look at Cucumber and JBehave, both of which allow specifications to be written in plain text.
If you choose to use FitNesse, it may also be worth looking at Slim, which sits behind FitNesse in place of Fit. It provides slightly different table formats to Fit, and I've found it suits BDD much better.
Just to update the topic, you can also consider jnario.
The majority of components available for Delphi do not have HTML Help files for Delphi 2009. Many components including some very popular commercial components only have HLP and CHM help files.
Many of the third-party components are no longer being actively developed but are used by many developers. As a result there is no IDE help for these components.
There were very few complaints about the old CHM help files but today there are a large number of complaints about the help file system. Maybe it is time for Codegear to rethink the type of help file system used.
One of the complaints that I have about it is even when you install components that provide HTML help files the Contents Tab becomes corrupted where by previously installed component contents are removed.
Are there possible alternatives for Codegear to consider?
I have the same feeling. The old help system helps me more quickly to find an answer.
One idea is to maybe to model it after the Delphi Wiki at: http://delphi.wikia.com/wiki/Delphi_Wiki
The wiki actually isn't set up that bad, especially with the VCL link in the left frame.
It's fairly pleasant to look at, has a decent search, includes issues, examples, cross references, and what I like the most: user comments and tips.
Actually regarding the user comments and tips, the thing I like most about the PHP documentation at www.php.net/docs.php (which I think is the best programming documentation I've seen) is the user comments and tips.
If they can integrate the great layout that you'll find at Delphi Basics into it, and allow 3rd party components to add their help files into it, then they'll have a complete reference. (But the 3rd parties will obviously have to restructure their help files to the new format - whatever it ends up as).
The wiki also has sections for Tutorials, Tips and Tricks, References and Popular Articles. And I think it could also become the all-encompassing code-repository we all would like.
An option to download the help wiki should be allowed so it can be accessed offline.
And they'll have to figure out how to get the F1 key to work to properly search the wiki/help file, whether online or offline, and give the most relevant results.
The trouble with the Wiki now is that it is not complete, and the full set of Delphi help files need to be incorporated into it.
This might be a pipedream, but something like this would be my ideal.
This is a pet hate of mine. The Delphi Help has just got worse, although with a recent slight improvement. I honestly believe that this is one of the things holding back its adoption.
Micosoft introduced Help3 for VS2010, so maybe we will see it in Delphi too:
here is a blog post which answers the question "Why A New Help System?"
http://thirdblogfromthesun.com/2010/10/the-story-of-help-in-visual-studio-2010/
It quotes an internal paper, which led to the new "Help3" project in
early 2008:
"The paper described the following
issues with the help experience in
Visual Studio:
Not being able to find the information you need is a common
problem. F1 Help and Search do not
work as well as they should.
The performance of the help system – primarily start-up, topic-load,
local search results – is one of the
biggest problems.
The offline MSDN library install is fragile due to the complexities of
the help system.
The proprietary nature of our help format offers little incentive for
partners to develop authoring tools
and cannot be easily adopted by
developers in their own products.
On the content production side, the help platform saddles us with
outdated tools and processes.
Finally, and most importantly, no single team at Microsoft owns solving
these problems."
What tools are available for metamodelling?
Especially for developing diagram editors, at the moment trying out Eclipse GMF
Wondering what other options are out there?
Any comparison available?
Your question is simply too broad for a single answer - due to many aspects.
First, meta-modelling is not a set term, but rather a very fuzzy thing, including modelling models of models and reaching out to terms like MDA.
Second, there are numerous options to developing diagram editors - going the Eclipse way is surely a nice option.
To get you at least started in the Eclipse department:
have a look at MOF, that is architecture for "meta-modelling" from the OMG (the guys, that maintain UML)
from there approach EMOF, a sub set which is supported by the Eclipse Modelling Framework in the incarnation of Ecore.
building something on top of GMF might be indeed a good idea, because that's the way existing diagram editors for the Eclipse platform take (e.g. Omondo's EclipseUML)
there are a lot of tools existing in the Eclipse environment, that can utilize Ecore - I simply hope, that GMF builts on top of Ecore itself.
Dia has an API for this - I was able to fairly trivially frig their UML editor into a basic ER modelling tool by changing the arrow styles. With a DB reversengineering tool I found in sourceforge (took the schema and spat out dia files) you could use this to document databases. While what I did was fairly trivial, the API was quite straightforward and it didn't take me that long to work out how to make the change.
If you're of a mind to try out Smalltalk There used to be a Smalltalk meta-case framework called DOME which does this sort of thing. If you download VisualWorks, DOME is one of the contributed packages.
GMF is a nice example. At the core of this sits EMF/Ecore, like computerkram sais. Ecore is also used for the base of Eclipse's UML2 . The prestige use case and proof of concept for GMF is certainly UML2 Tools.
Although generally a UML tool, I would look at StarUML. It supports additional modules beyond what are already built in. If it doesn't have what you need built in or as a module, I supposed you could make your own, but I don't know how difficult that is.
Meta-modeling is mostly done in Smalltalk.
You might want to take a look at MOOSE (http://moose.unibe.ch). There are a lot of tools being developed for program understanding. Most are Smalltalk based. There is also some java and c++ work.
Two of the most impressive tools are CodeCity and Mondrian. CodeCity can visualize code development over time, Mondrian provides scriptable visualization technology.
And of course there is the classic HotDraw, which is also available in java.
For web development there is also Magritte, providing meta-descriptions for Seaside.
I would strongly recommend you look into DSM (Domain Specific Modeling) as a general topic, meta-modeling is directly related. There are eclipse based tools like GMF that currently require java coding, but integrate nicely with other eclipse tools and UML. However there are two other classes out there.
MetaCase which I will call a pure DSM tool as it focuses on allowing a developer/modeler with out nearly as much coding create a usable graphical model. Additionally it can be easily deployed for others to use. GMF and Microsoft's Beta software factory/DSM tool fall into this category.
Pure Meta-modeling tools which are not intended for DSM tooling, code generation, and the like. I do not follow these tools as closely as I am interested in applications that generate tooling for SMEs, Domain Experts, and others to use and contribute value to an active project not modeling for models sake, or just documentation and theory.
If you want to learn more about number 1, the tooling applications for DSMs/Meta-modeling, then check out my post "DSMForum.org great resources, worth a look." or just navigate directly to the DSMForum.org
In case you are interested in something that is related to modelling and not generation of code, have a look at adoxx.org. As a metamodelling platform it does provide functionalities and mechanisms to quickly develop your own DSL and allows you to focus on the models needs (business requirements, conceptual level design/specification). There is an active community from academia and practice involved developing prototypical as well as commercial application based on the platform. Could be interesting ...