SourceLinesAndDocu
From Java4c
Contents |
Navigation
- up: Main_Page
- down basics: TODO
Overview
Lines of code are many lines - only the developer of them looks through it. Or?
Sources have a structure. It is the formal syntax of the language primary. Code lines are top-down structures of classes, data-struct, methods, statement blocks. They can be analyzed formally and presented in there structure. Modern programming environments do so.
Advantage of textual source lines in comparison with graphic programming
- Code lines - change tracking: Older and newer versions of sources are able to compare. All source version systems support that. It is possible to track which functionality is changed why, when, who and what exactly.
- Graphical programming - change tracking': If there is a textual representation of the graphical appearance, it is possible to track changes line code lines too. Only it is another notation. But some graphic programming systems stores there content in special maybe binary files or a database adequate form, which doesn't allow a simple comparison of content.
- Code lines - searching anything: Because they are textual files, a grep or ordinary search of text can be applied. Sometimes any textual hint is given to search the proper line. For example there is a textual sequence in an error message or a label on a button - search it in code lines of all files and you find the line where it is handled, without knowledge and understanding of the whole structure of the software.
- Graphical programming - searching anything': It may be a search function in the graphical programming environment. Is it proper to use?
Summary: Code lines are better to handle but graphic programming is better to understand. Use a graphical programming environment with a simple representation of its content in code lines.
Generating documentation from code lines
- The code lines are the first (hack first ideas) and last (debug errors, implement features) which are touched by the programmer. Some programmers don't like writing documentation.
- Documentation outside of the code doesn't seem to be actual. Is it corrected in progress with the code changing?
javadoc - Java source documentation
javadoc is a generator to produce html-pages from Java sources. It is a part of any standard Java developer kit.
- The appearance of the code is the same worldwide. It is a standard. Anybody Java developer knows it.
- The writing styles of comments in the sources are the same worldwide. Anybody Java developer writes with the same style guides.
- Writing comments for javadoc style is supported by tools, for example in eclipse.
- An example produced with javadoc from me: [LocalIdents.java]
- An example with graphical content. The source file is used only as base for documentation. [Docu.java]
- An example from Sun/Oracle: [String.java]
- An example from apache: [DOMImplementationLS.java]
You can see - all styles of documentation are comparable. The kind of presentation of the functionality is equal.
In the html presentation you get the links to all types automatically without any effort in the source.
The thinking is:
- Comment the function and mission of any variable or association (pointer to other class or data struct).
- Comment the function and mission of any method. Write shortly what the method does.
- Write one sentence for core function and mission.
- Write some sentences for details.
- You can use lists using the html-known tags < ul>, < li> etc.
- You can write tables using < table> etc. But that is more complex.
- You can use html-links for example for images in the html presentation. In the code you see the name of the file (the link)
- You can use links to other elements of the source! It is written {@link class#method(paramtypes)}. Eclipse helps you while selecting with the usual write completion functionality.
The thinking of commenting influences the thinking to a good software structure and proper identifier. If you write the comment, you will think about the meaning of the code elements and you will correct it if it isn't proper.
Doxygen
[doxygen] is a usual documentation generation system used for C and C++ sources often. Doxygen has a lot of adjustment possibilities to control the kind of comment designation. It has a lot of possibilities to generate cross references of code and so on. Therefore it is more multifaceted.
Using javadoc styles for C and C++ sources
The javadoc notification style of comments in source code is widespread in most of sources. It is possible to use for doxygen too, if the doxygen control files are adjusted for that style. The basic write style is:
/**Comment core function in the first sentence. * Some more information if necessary.*/ int x;
The comment is written before the element.
/**Comment core function in the first sentence.
* Some more information if necessary.
* A {@link OtherClass} in the explanation appears in a html-link
* for a proper navigation.
* - Some remarks are proper able to read in lists. *
- next list bullet. *
* @param par the explanation of the parameter * @param par2 the next * @return explanation what returns the method * @throws IllegalArgumentException explanation of exceptions if there are any */ int myRoutine(int par, float par2);
You can write some elaborate explanation if necessary. But think about correction if the parameter of a method are changed or details of the functionality are changed.
Generating an UML-Model from Headerfiles
TODO
