Just saying "document your code, documentation is good" isn't going to raise the code quality. There's different types of documentation and different situations where documentation should or should not be written. In object-oriented languages such as Java, interface documentation has very important role. To create a simple and quick documentation of your API, JavaDoc is enough. To create an interface documentation, which would explain the usage of the interface, write a unit test, which tests the class behind that interface. Nothing will explain the usage of interface better than the usage example code itself. If the class implementation is using some complex algorithm which should be documented, probably the best approach would be to encapsulate that algorithm into it's own class and plug it into the system with some appropriate design pattern (Strategy, for example), so the documentation "raises" from inner source code level to the class level. If higher-level issues should be documented and explained, such as architectural decisions or more implementation-specific issues like "why we're using algorithm A and not the simpler algorithm B" then source code isn't very good place to write that information (per-component or per-package design documents should be considered in these cases).
Have anyone tried AppleScript? It's very close-to-natural scripting language, and personally, I think it's awful. For me it's much easier to write things in PHP, Perl or Java than in "human speakable" AppleScript.
Slashdot Mirror
Just saying "document your code, documentation is good" isn't going to raise the code quality. There's different types of documentation and different situations where documentation should or should not be written. In object-oriented languages such as Java, interface documentation has very important role. To create a simple and quick documentation of your API, JavaDoc is enough. To create an interface documentation, which would explain the usage of the interface, write a unit test, which tests the class behind that interface. Nothing will explain the usage of interface better than the usage example code itself. If the class implementation is using some complex algorithm which should be documented, probably the best approach would be to encapsulate that algorithm into it's own class and plug it into the system with some appropriate design pattern (Strategy, for example), so the documentation "raises" from inner source code level to the class level. If higher-level issues should be documented and explained, such as architectural decisions or more implementation-specific issues like "why we're using algorithm A and not the simpler algorithm B" then source code isn't very good place to write that information (per-component or per-package design documents should be considered in these cases).
Have anyone tried AppleScript? It's very close-to-natural scripting language, and personally, I think it's awful. For me it's much easier to write things in PHP, Perl or Java than in "human speakable" AppleScript.