Download ROSE Compiler Framework

Source Code Documentation
16.10.1 General Guidelines
• English only
• Use valid Doxygen syntax (see "Examples" below)
• Make the code readable for a person who reads your code for the first time:
• Document key concepts, algorithms, and functionalities
• Cover your project, file, class/namespace, functions, and variables.
• State your input and output clearly, specifically the meaning of the input or output
• Users are more likely to use your code if they don't have to think about what the
output means or what the input should be
• Clever is often synonymous with obfuscated, avoid this form of cleverness in coding.
TODO, not ready yet
• Test your documentation by generating it on your machine and then manually inspecting
it to confirm its correctness
TODO: Generating Local Documentation
This does not work sometimes since we have a configuration file to indicate which directories
to be scanned to generate the web reference html files
$ make doxygen_docs -C ${ROSE_BUILD}/docs/Rose/
16.10.2 Use //TODO
This is a recommended way to improve your code's comments.
While doing incremental development, it is often to have something you decide to do in the
next iterations or you know your current implementation/functions have some limitations to
be fixed in the future.
A good way is to immediately put a TODO source comments (// TODO blar blar ..) into
the relevant code when you make such kind of decisions so you won't forget here is something
you want to do next time.
The TODOs also serve as some handy flags within the code for other people if they want to
improve your work after you are gone.
16.10.3 Examples
Single Line
Often a brief single line comment is enough
//! Brief description.
107