How much do you comment your source code?

How much do you comment your source code?

No matter what you think the "perfect amount" of code commenting is, let's agree that high-quality comments are important in open source.

A bunch of question marks
Image by :

Subscribe now

Get the highlights in your inbox every week.

How frequently do you comment your code?

While it may be true that the best code is self-documenting, even the clearest written source code requires adequate documentation in order to be quickly parsed and understood by human readers.

In practice, though, where and how much to comment is much more up to the individual developer to decide than elements of the code itself. The compiler or interpreter doesn't generally care about your comments; after all, they're not for it, they're for us humans. And so while some organizations and projects will offer guidelines, commenting styles are much more open to interpretation.

In general, being clear and concise with your comments will be appreciated. But particular within open source, you don't have the luxury of assuming that other developers looking at your code are familiar with the context in which it was written. Everyone is new to the project at some point, and you can't count on them understanding the project's history, its quirks, or the libraries it uses. New contributors may not be native speakers of your language, either.

And so well-written and well-placed comments are an important part of your project's documentation. Are you making sure that your project's code is as accessible as it can be?

How often do you comment? Do you think you comment frequently enough? Let us know what you think!

About the author

Jason Baker - I use technology to make the world more open. Linux desktop enthusiast. Map/geospatial nerd. Raspberry Pi tinkerer. Data analysis and visualization geek. Occasional coder. Cloud nativist. Civic tech and open government booster.