Writing Great Documentation
Don't
Ok. Clearly I am joking. Well half joking, at least.
Everything rots. Rotten documentation is never good documentation, even if it started out that way. Your projects contents will rot in this order:
- Documentation
- Readme's
- Comments
- Code
External documentation is almost useless after any amount of time; So don't write it. Having bad documentation is worst then have no documentation. A confused developer is far more dangerous then a developer that isn't sure of something.
There are things that need to be documented, but don't think of them as documentation. If you have an API layer, you should write a spec sheet. And I mean do this before you implement your API. Sure it will change, then updated it. But once your API is locked down, you don't have to worry about changing your sheet. Bonus points for using generated documentation like Swagger
Side Note: And for the love of god, dogfood your API!
Readme's can be important, they gain the benefit of being easier to change since they are sitting in the repo(and are hopefully markdowns). Anytime I see anything documented in Word or PDFs I worry(and cry). The bigger the cost of change, the less it will get changed. Readme's should really include abstract things, and how to get the project running. Avoid implantation details, anything that might change.
CHANGELOG and TODO files can be good, but only if you remember to update them. There are ways to generate changelogs from git and todo's from comments. Prefer this over manual.
As a rule don't comment your code. If you have to comment your code, you should rewrite/refactor your code so that its apparent of whats going on. This will improve your codes maintainability and remove your comment rot. Win/Win. Self-documenting code is pretty much the only thing that will survive the test of time in any given project.
- Namespaces should describe context
- Classes should describe resources
- Functions should describe actions.
- Helper Functions should describe simple actions.
- Paragraphs( or blocks) of code should be of a single thought.
- Sentences( or Lines) of code should be doing a single thing. [If I have to think about the order of operations, your doing it wrong]
Written by Zane Wolfgang Pickett
Related protips
9 Responses
Anytime I see anything documented in Word or PDFs I worry(and cry). 100% Correct!
As a rule don't comment your code. This is a matter of taste. I like having sparse comment explaining briefly what each function or class does. This is also the way to produce beautiful documentation using tools like sphinx.
But in a way you wrote down the essence of what tools like sphinx encourage you to do.
I agree with oz, also sometimes its a matter of principle/rest of the codebase has function comments. I recommend writing function comments in a way that they are unlikely to change. Commenting on what a function does is great, commenting on "how it does it" leads to the problems you are discussing when the implementation changes.
Certain systems do gain stuff like auto complete from some basic comments, outside of that; I would argue that the function name should tell you everything you need to know. If you can't describe what something does in its name, your probably trying to solve too many problems in that function.
I also forgot to point out how tests are often the best documentation for functions.
I also forgot to point out how tests are often the best documentation for functions. +1 For that!
If I see a python module foo.py and test_foo.py I know I have a good project at hand. I will than open vim in split mode and read both in parallel!
This is all new to me but what is the "function name"?
@hoffoo whats the best way to learn code?
Comments should be sparse but I like to use them if the code/business logic might not be intuitive. You might ask why isn't it more intuitive and some times it just can't be done or maybe the style of the language makes it less intuitive. I don't know where I saw this but, "well written code is like a good joke, it doesn't need an explanation"
That reminds me, I found this awhile back for business logic: http://brewhouse.io/blog/2014/04/30/gourmet-service-objects.html
I think it solve the problem in most cases rather nicely.
Love the summary at the end:
Namespaces should describe context
Classes should describe resources
Functions should describe actions.
Helper Functions should describe simple actions.
Paragraphs( or blocks) of code should be of a single thought.
Sentences( or Lines) of code should be doing a single thing. [If I have to think about the order of operations, your doing it wrong]
Like poetry.
