Writing documentation is typically an addition to writing comments. They serve different purposes. That said, adding a diagram to a comment will only make it easier to read. It is an addition. It cannot make things harder.
I agree that docs and code comments should complement each other. As a visual learner, I find diagrams showing how classes/objects fit together to be much more helpful than reading the documentation. A picture can replace a thousand words and tools like Vizio/Yed are really helpful in my opinion while at the same time minimizing the amount of documentation.
OT, but this is my number one peeve with code documentation: going to the effort to write a doc comment, taking up at least 6 lines, probably using some special syntax, cluttering up the code, but then adding no information that can't be derived from the signature.
If you're not going to document something (which I totally respect), at least don't make the code worse while doing it.
I was hesitant to include the documentation part of my comment for the exact reasons you mention. In fact, documentation often is just somebody’s notes.
I know it's not sexy, but adding lots of comments to the code will help to keep things organised, and will make your life next year sooo much better.
For higher-level concepts, usage examples, declarations of intent and expectation I cannot recommend "official" documentation more.
A lot of my career exists because I was forced by circumstance to write formal docs for my work. I refer to my own docs multiple times every day. Other people use my work because its documented.
And when I have to return to code, i find myself adding ever more comments to help me digest it. Personally I've never looked at code and thought "I can't use this, too many comments, too much documentation".
While I'm working I'm also writing (and rewriting) the docs.
For casual scribbles I use paper. I throw that away from time to time to reinforce how ethereal that is.
I have a motto now - if it's not documented, it doesn't exist. For me it matters 10x more than actual code, because it makes the code reusable, reliable and dependable.
Documentation isn't a bad word - I regularly make documents to describe the architecture of my projects, along with their an outline of how to get into the codebase, for example. Comments are also documentation, though, and in this case comments are the right place. If I'm looking at a configuration option and thinking 'That seems a bit odd. Why do we have that set?' I want to be able to see the reasoning right there, not have to hunt through a wiki in the hope that someone has put their reasoning somewhere.
In my experience, comments are less likely to go stale than wiki docs.
When working on or editing documentation or the comments, I start with the "two-year-old kid" review. I ask myself "why" and "what", and often repeatedly, until I get to a concise answer.
What's this? Why is this here? Why do I want it? Why is this good? Why do I care? Why? What's that mean? What's this knob do? What's that code do? Why is this code here? Why?
Flabby documentation, user documentation written in programmer jargon and scatter-shot code comments are all comparatively easy to write. When somebody bothers to write that.
Writing for the end-user (whoever that might be) is tougher, and I find require iterating on the content of the documentation, UI, release notes, comments, or whatever. Writing less documentation or fewer comments — while conveying the necessary details — is hard work.
I would never suggest documentation in code alone... Your point is very much noted, echoed and a hat-tip to you here. Yes, documentation is incredibly important, and it should be used as an driver/accompaniment along with comments.
For the first question, putting the documentation into the source code has a major problem, there is no good place to put an overview of the whole system. Block diagrams are difficult to draw with just ASCII, images can't be included, formulas, and more. Also many things in software connect to many other things, and if the documentation is in the source code you can likely only describe one side of these connections (or you have to describe both fully on each side of the connection, thus duplicating a lot of the documentation.) Comments are immensely useful, but I don't think they work for general purpose documentation of a system. They can work well for libraries where each API needs to be described separately, but even then I wouldn't consider them complete documentation of a library (how do you combine graphics functions to build a rendering pipeline for example, do you have to described how to build pipelines for every single function that might be used in a pipeline?)
Sometimes, the mere process of writing documentation (or a specification) can lead the author to a better understanding and helps uncover problems. Writing, in this case, is an aid to thinking. It may not be the best-case scenario, but it's not a total waste of time, either.
Documentation (including code comments) are vital and important, but it's far better to bake the proper constraints into the code/specs so that it's hard to make mistakes. Then the docs are less necessary, shorter, and easier to understand. I think this is what GP is getting at.
I agree that bad documentation is a serious problem in many cases. So much so that your suggestion to write the documentation after the fact can become quite impossible.
If there is only one thing that juniors should learn about writing documentation (be it comments or design documents), it is this: document why something is there. If resources are limited, you can safely skip comments that describe how something works, because that information is also available in code.
(It might help to describe what is available, especially if code is spread out over multiple repositories, libraries, teams, etc.)
(Also, I suppose the comment I'm responding to could've been slightly more forgiving to GP, but that's another story.)
Each has a different audience and requires a different structure and writing style.
I once spent a project being the lone wolf against my will, writing tons of documentation with diagrams. Didn't matter, if anything it just made the rest feel insecure and look bad. Everyone says they want docs but often they don't, really, because they don't read them when they do exist.
Documentation is written in a human language, can include other media like graphics and is addressed to humans. We write documentation for the same reason that we don't produce maps at a 1:1 scale: documentation offers a higher-level description that can be grasped without having to understand all the code.
Not only is code not the best documentation, it's not documentation at all, outside of special cases where the entire code describes e.g. an algorithm and is encapsulated into one function.
Yeah.. in a world with infinite time and no compromise, documentations + diagrams are nice. In practice, working on this means not working on something else, potentially more important. Trade-offs are hard and not fun :(
I think this could be another brilliant addition to the "documentation view". Imagine a multi-tabbed documentation pane. The first tab lets you write normal comments, but in another one you could write doctests like the example you gave, or even assertion of pre and post conditions.
Really, I think that's the only way to learn some things.
Good documentation and comments always seem like a hassle... until the first time you have to go fix a bug on something you wrote 18 months ago and have no clue how it works.
reply