3 ms·

Comments in code often only describe the task at hand, and rarely ever the big picture of how code fits together or why. Documentation, test cases(and comments)

Comments in code often only describe the task at hand, and rarely ever the big picture of how code fits together or why. Documentation, test cases(and comments) and internal FAQs cover these to some extent, but are disassociated from the code itself. IMO to think inline code comments are as important as they are misses the forest for the trees; I want to see the solution to these bigger problems. Moreover (and this is a separate problem altogether) most code comments are text based-Are there examples of non text commenting that have taken off? Often an algo or structure is so much better described with an image or video- yet most comments are text based. There’s much to come in the way of comments- there must be.

MaulingMonkey 8y ago
> Often an algo or structure is so much better described with an image or video- yet most comments are text based. I've written my fair share of ASCII diagrams. I've also smuggled links to wikis into my doc comments for e.g. cross platform abstractions for on-screen keyboards. Then I can link all the screenshots I want. Or to gifs/videos for shader effects demos. Or to a series of images and code snippets for tutorials, or ... Heck, if you're using markdown doc comments, there's no reason you couldn't embed image URLs that get expanded directly into inline images by the doc generator...
bunderbunder 8y ago
If I need to document something in a way that doesn't fit into a comment, I'll add a separate document to the source repository and then add a comment that references it in the code. If you're using something like GitHub that gives you a Web interface that renders Markdown files, the ergonomics of doing it this way are really pretty good. I feel like this is the best way to document "big picture" stuff in general. You don't want to just have the comments, because, if you carve it up into a bunch of little vignettes and scatter them around the code, it's no longer a big picture. But external documentation alone is also insufficient. If you don't mention when it's relevant, at the spots where it's relevant, then you can't rely on people to know when and where to look for it.

MaulingMonkey 8y ago

> Often an algo or structure is so much better described with an image or video- yet most comments are text based. I've written my fair share of ASCII diagrams. I've also smuggled links to wikis into my doc comments for e.g. cross platform abstractions for on-screen keyboards. Then I can link all the screenshots I want. Or to gifs/videos for shader effects demos. Or to a series of images and code snippets for tutorials, or ... Heck, if you're using markdown doc comments, there's no reason you couldn't embed image URLs that get expanded directly into inline images by the doc generator...

bunderbunder 8y ago

If I need to document something in a way that doesn't fit into a comment, I'll add a separate document to the source repository and then add a comment that references it in the code. If you're using something like GitHub that gives you a Web interface that renders Markdown files, the ergonomics of doing it this way are really pretty good. I feel like this is the best way to document "big picture" stuff in general. You don't want to just have the comments, because, if you carve it up into a bunch of little vignettes and scatter them around the code, it's no longer a big picture. But external documentation alone is also insufficient. If you don't mention when it's relevant, at the spots where it's relevant, then you can't rely on people to know when and where to look for it.