Inline documentation is a sore subject for a lot of developers. Many see it as wasteful; it easily becomes stale, it’s yet-another-thing to maintain, and if you can already read your language of choice, it doesn’t provide any real value.
Documentation is not for you; it’s for everyone else. (Well, it’s for you too, but the future you.)
Avoiding comments because your code is “readable and understandable” makes several assumptions about your audience, such as them having any working knowledge of the language you’re programming in.
Our jobs (specifically as leaders in open-source communities) are to grow the platforms we’re responsible for. By catering to only developers, we end up ruling out contributions from everyone that isn’t currently a developer at our levels. That’s sad for everyone.
The natural response is: if you need to add a comment to your code, you’re being too clever. This, again, makes assumptions about your contributing audience. Thing is, it’s not about adding comments to difficult-to-understand or poorly-written code, it’s about translating gibberish into plain English so a bigger audience can contribute.
Inline documentation is the nonce-check of the open-source universe; it promises what’s actually happening in gibberish-land matches the intention of that section of code. There are a million excuses not to document your code, but it all boils down to either:
- Being selfish.
- Being lazy.
- Being in a hurry.
- Not knowing any better.
- Being so insanely good at reading everyone else’s code that documentation has never in any way helped you.
Rarely is #5 the case; that only leaves ignorance and carelessness, which are unacceptable if you respect and admire your colleagues, users, and the efforts of your communities and teams of developers.
So, please… document what the heck you’re trying to do.
+1000! I’ve been saying this a lot recently. If nothing else, commenting helps less experienced developers to learn more and that’s always a good thing.
I guess the downside of commenting is that in some cases people who know nothing about code start fiddling with it because they know where to look. Therein lies darkness.
I would argue that, separately, documentation is also for you the developer. I’ve found quite often that my inline documentation can be a very effective breadcrumb trail when establishing ones own intent, particularly with regard to complex function arguments and usage. And it’s also helpful to return to a function two years later and find a paragraph in the inline documentation that describes, in meticulous fashion, something that I otherwise would have had to rediscover all over again. I think clear inline documentation is on par with strong commit messages.
No argument here; I love when that happens.
Totally agree about commit messages. I’ve recently started being much more verbose with them, to the point where they are sometimes larger than the code changes themselves.
Yes exactly! Its also worth considering that unlike the old style of comments throughout code, these days the important thing is the function summary. A dev writing 2 sentences can let me skip having to read 100 lines of code! Such a good deal for us both!
The other big one is a comment to explain an action/filter use in a plugin. Why not take 10 seconds and let me know what you’re planning there?
JJJ I might also add another item to your list of excuses “It’s tedious to write PHODoc”. This one is actually pretty good except that people just need to figure out how to automate it, which is exceptionally easy with IDEs like Netbeans, but must also be doable with any high quality editor.
Pingback: Writing Effective Documentation For WordPress End Users | t1u
Pingback: WordPress Theme Best Practices - YinPressYinPress