Tag Info

Hot answers tagged

57

This is awesome. I wish more software developers took the time and effort to do this. It: States in plain English what the class does (i.e. it's responsibility), Provides useful supplementary information about the code without repeating verbatim what the code already says, Outlines some of the design decisions and why they were made, and Highlights some ...


12

The key to working with a large codebase is not having to read the entire codebase to make a change. To enable a programmer to quickly find the code he is looking for, code should be organized, and the organization apparent. That is, each logical unit in the code, from the executable, the library, the namespace, down to the individual class should have a ...


5

It's generated by GhostDoc / JAutoDoc. This kind of "documentation" that merely translates a member name to English based on capitalization or underscores is useless as hell, but at least it makes the code inspectors that flag "undocumented member" as warnings shut up.


1

I'm personally a fan of a high-level design document - preferably written BEFORE any code - that gives an overview of the design and a list of classes and resources. A top-down design greatly simplifies things - yours might be "game engine -> hardware -> controllers -> joystick"; thus, a new programmer told "fix the 'a' button on the 'xyz controller" would ...


1

What do you call the stuttering type of documentation? "undocumented code" "part of the problem" "almost documented code" Clearly writing the method names in English fulfills the inexperienced programmer's desire to document everything, without making them actually do any documentation. No, not clearly. This type of documentation is usually the ...


1

Source code and documentation the way it should be done. http://jasmine.github.io/2.3/introduction.html



Only top voted, non community-wiki answers of a minimum length are eligible