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.
* <ul><li>Some remarks are proper able to read in lists.
* <li>next list bullet.
* </ul>
* @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
One of the disadvantage of code lines and documentation lines is: It has only one dimension, from to do down. If you have cross references to other code parts or chapter in a document, only links are able to use.
The advantage of [[http://en.wikipedia.org/wiki/Unified_Modeling_Language UML (Wikipedia) is:
- The relation between parts of a software are shown in 2 dimensions. It is in an area, not only in lines.
- There may be more as one presentation possible to show relations between the same software parts.
An representation of C software in form of UML diagrams is a good documentation.
Usual the direction of work is thought from the UML model to the code. It is automatic code generation. It presumes, that a developer is more friendly with UML diagrams but with source lines.
But often programmers are more conversant in writing code lines. If some details of implementation should be regarded, the code lines are the nearest way to notify it. Therefore the generation of UML from code lines is proper too! It is similar to generate documentation from code lines.
XMI and UML repository
The [XMI (Wikipedia)]-Format is the data-interchanging format for UML. It is standardized for all UML tools.
A repository is the database for all UML diagrams managed in a UML tool.
The repository can be represented in the XMI format. The converter from C headerfiles to UML converts header files to a XMI-format-repository. The XMI file can be inputted in a UML tool. Then diagrams can be created with this given database using a UML tool.
Tools to generate XMI from header files
The converter contained in the download [ZBNF (sourceforge)] parses headerfiles and then generates an XMI-file. The download contains a folder zbnfjax which should be copied to a proper location on the local harddisk. This folder contains all jar files (Java archives) and scripts to work. Additional there are necessary
This software tools should be downloaded and placed on the hard disk too.
On a linux system I have copied it to
/usr/share/XML_Tools/ -rwxrwxr-x 1 root root 153253 13. Feb 2008 jdom.jar drwxr-xr-x 7 root root 4096 12. Mär 2010 org.apache.ant_1.6.5 -rwxrwxr-x 1 root root 5468048 22. Okt 2009 saxon9he.jar -rwxrwxr-x 1 root root 5046534 28. Okt 2009 saxon9.jar -rwxrwxr-x 1 root root 37139 28. Okt 2009 saxon9-jdom.jar
/usr/share/vishia/ lrwxrwxrwx 1 root root 50 3. Jul 05:41 zbnfjax
/usr/bin/ -rwxr-xr-x 1 root root 76 3. Jul 05:41 zbnfjax
The last file is the start script for all zbnf commands. It is placed in the systems PATH because the translation is invoked using
>zbnfjax options
as line command.
On windows it is adequate. The tools are the same.
