Good Developer Habit #3: Leverage Standard Documentation Conventions
Make sure you learn the simple formats in your language of choice for documenting (Javadoc, Doxygen for C++, Perldoc). Why? Besides generating HTML, PDF, etc. documentation users can read without loading source files, many modern IDEs (Eclipse, etc) parse documentation and can present it as you mouse over on code statements.
Java/C++
At the very least you should have Javadoc and Doxygen have very similar styles, the examples below comply in both system. the following docs for any source file:
/**
* @class MyClass
*
* Describe what the heck your class does, threading expectations,
* how it should be used, etc.
*
* @version $Id: $
*/
public class MyClass {
And for all public methods that you expect others to consume:
/** * @return a Collection of Mojo, or empty Collection if has no Mojo */ CollectiongetMyMojo();
Bonus points for including threading and concurrency expectations, exception behavior, performance hints.