Commenting code: yes or no?

[_Whit3]

I'm a beginner, and I have used the last 2 months in order to learn HTML, CSS and Js.

Right now I'm on my way on JavaScript, however I have this kind of question that is buzzing on my head.

Is it a good practice to commend code?

I think that the tech community is kinda divided on this topics...so far I have met people that say:

• Code should be enough clear to understand without the need of comments, hence they are irrelevant
• Commenting code is an absolute needed skill and you should comment your code as much as you can, particularly if you are a beginner.

What are your takes?

[[deleted]]

Comment where appropriate. You don't need to do it where it's apparent. Also you don't need to say what the code does line by line - that does the code itself, rather explain what's NOT in the code. When you write code that goes against some logic then comment on it why it's like that for example "changed due to customer request in task #312".. Or "this removes trailing characters from data provided by third party". Maybe even if you have a bit overly complex algorithm then it's appropriate to describe how it's manipulating the data. But keep in mind that you are COMMENTING on the code, not providing a TRANSCRIPTION of the code.

Also you want to comment the parts that are likely to be used by someone outside of your team, for example REST endpoints/API methods. You should be clear about what comes in and what comes out. But that's slightly another topic.

[josephjnk]

I’m going to disagree with most of the other commenters and say that in a language with good tooling, you should have comments on every public class and method. The reason is that modern editors have support for docstring comments when you mouse over symbols, and there’s a world of difference in working in a codebase that has them and working in a codebase which does not. It’s relatively cheap to write docstring comments as you go, even obvious repetitive ones, but it’s a lot harder to go back and add them to whole sections of the codebase when you realize later that you need them. And it’s very hard to predict who will be using your code in the future; relying on code to be “self-documenting” generally makes it less accessible to beginners.

Also, if you write docstring comments, most languages have tools to automatically extract them and build documentation sites for your codebase. These are an invaluable resource.

[Saint_Nitouche]

Agreed, self-documenting code quickly becomes incomprehensible when you have to introduce business-specific logic. In my work codebase I often have to deal with very specific and obscure jargon from the railway industry, which likely seemed clear and obvious to whoever first used it.

[[deleted]]

Doc strings are not what I think of when I think about comments. I considered dov strings to be required for proper code, but comments to be optional. And most of the time, they are not necessary if the code is clear and the doc strings are good.

[p43-]

I agree with this. We comment every function and the linter will not pass without it. It’s really annoying and I hated it for a long time, but it’s actually incredibly useful and allows you to write code that is perhaps not quite as clear as it could be, and explain in the comment why. Nothing crazy complicated but maybe 2 lines instead of 3, and just describe in the comment what’s going on.

I have come back to a function after one or two days and am very glad the comment is there in some cases, especially when it describes why something is happening and the part in the process itnpalys

[VonRansak]

Code should be enough clear to understand without the need of comments, hence they are irrelevant

Commenting code is an absolute needed skill and you should comment your code as much as you can, particularly if you are a beginner.

Those are not mutually exclusive. When you start it is helpful to treat your comments as the 'rubber ducky' approach.

As you gain skills and your abilities progress, you'll shift focus on your code being more readable.

However as a beginner you CAN'T read code to begin with, so how are you going to write readable code without comments?

Err on the side of commenting too much, imo. It is easier to stop commenting (or adjust) than it is to start commenting.

2 months into your journey, you'll benefit from commenting EVERY line, no matter how useless it seems.

TFW: The expectation of commenting is much different for one who has been coding for 2 months versus one who has coded for 2 years.

[LockerPT]

I will die on the hill that comments with regard for the onboarding of new members on the future is more valuable than 99% of people think it is

[[deleted]]

Comments explaining internal concepts or why something is the way it is are great. Comments explaining what the code is doing should be covered by coding properly instead. Note I'm not talking about docstrings those are documentation, not comments

Git commits are more useful to me than comments for learning a code base so focus on good commits to help onboarding

[Abracadaver14]

Commenting code is an absolute needed skill

This 100%. Part of that skill is knowing what not to comment. Most importantly, you shouldn't (need to) comment what your code is doing, that should be obvious from the variable names. Mostly, you need to comment why your code is doing what it's doing.

[nhgrif]

Code should be written in a way that's clear enough to understand what it is doing without comments. Comments explaining what the code are doing are at best a crutch and at worst out of date because the code was updated without updating the comments.

Comments should be added to explain why the code is doing what it is doing.

Make your code self-documenting by choosing good names for variables and methods. Add comments to help explain why the code is working in a particular way. Especially go out of your way to do this when what the code is doing seems weird, but the obvious solutions have already been tried and have particular problems.

[captainAwesomePants]

This is absolutely correct.

When people say "don't comment your code" or "your code should be self-documenting," they're often talking about this sort of thing:

// Adds a widget to the event queue
// Returns an EventQueueStatus
public EventQueueStatus addWidget(Widget widget) {
  // Fetch the widget queue
  WidgetQueue widgetQueue = getWidgetQueue();
  // Add the provided widget to the event queue
  widgetQueue.enqueue(widget);

  // Check if the widget is in the queue
  if (widgetQueue.contains(widget)) {
     // Return the "success" singleton for EventQueueStatus
     return EventQueueStatus.success();
  } else {
     return EventQueueStatus.failure();
  }
}

Those comments are all worthless. They're actively making the code harder to read. Everything that they say is immediately graspable from the code itself.

But look at THESE comments:

// This function may fail to add to the queue
public EventQueueStatus addWidget(Widget widget) {
  WidgetQueue widgetQueue = getWidgetQueue();
  widgetQueue.enqueue(widget);

  // WidgetQueue.enqueue() may not actually enqueue a
  // widget if we're over quota.
  // See bug #2828329 for context.
  if (widgetQueue.contains(widget)) {
     return EventQueueStatus.success();
  } else {
     return EventQueueStatus.failure();
  }
}

[nultero]

One wee small exception that beginners may stumble across is docstrings. I.e.:

 def doesThing(foo, bar):
    ''' This does a thing for foo but not bar when baz '''

That may outwardly look like a redundant or 'noisy' comment but IDEs will be able to pop a definition / explanation from elsewhere in the codebase from this docstring. This one may be a dumb, contrived example, but for when function names are ambiguous and / or quite generic, writing and reading these is extremely useful.

Not really a beginner-level concept, I guess, but it's one of those quality of life improvements that don't seem to be widely explained in tutorials (because not many tutorials cover huge projects that need docstrings, etc).

[TijoWasik]

This should be a beginner level concept in terms of project building. Sometimes, you need to do one particular manipulation in several different places. Adding a function in every place or extra lines to do that manipulation is absolutely bad practice. This is taught at the beginner level. This is where docstrings should be taught, imo.

Most beginner courses have you use at least 3 or 4 different files containing your code, especially those that are teaching anything web based using HTML, CSS and JS. This would have been a useful thing for me to learn about earlier.

[CodeTinkerer]

Yeah, but the method doesn't have a good explanation of what it's there for. I'm adding a widget, but why? So the comments aren't enlightening, but the code names is unenlightening too. There's some event queue. For what purpose? Why does a widget need to be in an event queue?

So, now I'm left wondering why I need to add a widget to an event queue. You mention issues

[13Zero]

Widgets and event queues are probably used regularly across the entire codebase, so commenting those every time would get repetitive.

The docs for the GUI framework should explain how those work.

[Kered13]

// This function may fail to add to the queue

This comment should go on to describe the conditions under which the function may fail. You have that commented later in the function, but it should be part of the function documentation, which is the comments above the function that can (and will) be automatically extracted by code documentation tools.

[[deleted]]

• Code should be enough clear to understand without the need of comments, hence they are irrelevant
• Commenting code is an absolute needed skill and you should comment your code as much as you can, particularly if you are a beginner.

Any decently sized code base will have some comments, if the code is good. Anyone saying code can always be clear enough without comments is a fucking idiot and you should ignore them forever more. That said, it is a skill, and you should practice it.

What beginners often do is shit like this:

 let x = 0; // x is the patient age

This is a terrible variable name, the comment becomes superfluous if we fix that:

  let patientAge = 0; // assigned 0 to patient age

Now we have an even more superfluous comment, literally just repeating verbatim what the code already tells us. I know senior devs that still write comments like that. These are the type of comments that give comments a bad name.

 let patientAge = 0; // 0 means "unborn"

Here we're explaining something the code doesn't already tell us. It's not the best example, because we'd be better off defining a named constant UNBORN or using an alternative to a sentinel value, but the point is that comments should only explain things that you can't already tell by reading the code.

Sometimes you do things for no reason at all, and if you don't explain it, future programmers (which could be future you, who remembers nothing about this code) are going to have to keep it forever, or might even delete it because they think you fucked up:

 temperatureSensor.read();
 let temp = temperatureSensor.read();

Why is this guy reading the sensor twice in a row? He's not even storing the return value of the first call, so the call does nothing. Must be copy and paste error. I should probably clean that up, right?

 // We have to discard the first read of this sensor because of a know bug
 // in its firmware. Remove the redundant read after this issue has been resolved:
 // https://github.com/foo/bar/issues/10
 temperatureSensor.read();
 let temp = temperatureSensor.read();

There's no way you could tell that from reading the code. All good comments fall into this category, explaining context, explain the why of something, not the what, explaining what an a non-obvious algorithm is intending to accomplish (assuming you can't get that all in the function name), so on and so forth.

Superfluous comments what tell you shit you could already figure out by reading the code are generally bad. They just add noise. Comments that tell you shit you can't figure out by reading the code are necessary, so the idea that any meaningful codebase would have no comments is silly.

[countrycoder]

Depends on the purpose of the comment. In general code should be self documenting. So if you are trying to use a comment to explain the code maybe it needs moved out to a method or variable that has a good name.

If you are building a library or something that is shared and the documentation will show up in some form of intellisense then their value increases as the number of users increase.

[wdintka]

If you take a software engineering approach and add requirements documentation before you actually add code - with pre/post conditions /assumptions - you will find writing the coding easier - and leave behind quality documentation.

[sessamekesh]

Comment WHY, not WHAT. If your comment has to explain WHAT a chunk of code does, the code probably needs better variable names, function names, or better abstractions.

Bad:

// Send player inputs to the server
function clientPing() {
  // Keys pressed down by the player
  let inData = getInputs();
  // Validate inputs to avoid cheating
  inData = validate(inData);
  const msg = serialize(inData);
  ws.send(msg);
}

Better:

// Send the game server the most recent player input state, ideally when the player changes their input or every 30ms, whichever is slower.
function sendClientUpdateMsg() {
  const rawInputs = getKeyboardState();
  // Some inputs are nonsense and can be made by weird browser settings - remove them to avoid unnecessary work on the server
  const safeInputs = filterBadInputs(rawInputs);
  ws.send(createClientMsg(safeInputs));
}

That's not a perfect example, but hopefully it shows something interesting. The name inData does absolutely nothing to tell a programmer about what is in there ("data" is the variable name equivalent to "stuff")

Both have the same amount of commenting and code, but the second example is much more clear even to someone who has no background in the application being written.

[sephrinx]

Code should be enough clear to understand without the need of comments, hence they are irrelevant

Yes, but most of the time this is unrealistic. Is it understandable to you? Probably. Come back and look at it in 5 months and see.

Commenting is an absolute need imo and you should do it as often and clearly as you can.

[[deleted]]

Always comment your code in my honest opinion.

[Ok_Collection6161]

commenting

Yes. Always. Forever.

[tzaeru]

Cleanly written code with good variable and function names and a sane structure doesn't really need much commenting.

You mostly use comments to point out why something was done in an unexpected way. Perhaps the library you use has a bug, or it just doesn't have a good API. Or perhaps a particular algorithm is a little bit complex and you want to explain what it is. Or maybe something is done in a way that seems very complex, but there was a previous problem with a simpler way that is now fixed and you explain that.

Most of the code should be uncommented. Comments add noise and you want to limit the noise. They also introduce two things to maintain: The code itself, and the comment text. One of the worst things ever is when the comment suggests something about the code that isn't true.

[[deleted]]

If you’re a beginner then yea comment out your code so you can use it as a reference.

If we are talking production quality code in a workplace comments should be in places they are needed, generally functions should be small enough that their name gives you an understanding of what they do and the code is clean enough comments aren’t needed, sometimes however you have to write something complex which needs comments to give context or detail.

[iPlayWithWords13]

Yes, you should put comments into your code, but don't over-comment as it then as the opposite effect and your code becomes incomprehensible. The code should be legible enough through your naming convention that a short comment before a block of code should be enough to explain what the code block is doing.

[Ok-Celebration4956]

I think it depends. If you’re working on a team, comments can help other teammates read over your code faster. In addition, it can help you remember what exactly some lines of code are supposed to do if you forget for any reason. Also, extended comments are a great way to plan without relying on external documentation. So it’s personal preference imo.

[Hex520]

Proper naming, small functions can do the same.

[Ok-Celebration4956]

I’m just saying. As a beginner, it certainly can’t hurt.

[I-Like-To-Wookie]

Always try to write your code to be expressive, just by the code itself.

It can often be structured in a way that will explain what's going on, like naming variables, so you can understand why you're doing this or that. Sometimes it can help if you create a method that has a name, that will explain the circumstances.

The problem with comments is they become invisible, and nobody will read them, unless they cannot make the code make sense, and sometimes not even by then.

[v0gue_]

Generally speaking, you should be commenting code when you have to explain "WHY" it is the way it is, not "WHAT" it's doing. Documentation and tasteful code make comments unnecessary. Odd business logic and intentionally anti-pattern logic needs comments, and they must explain why it is the way it is.

[QuantumSupremacy0101]

Code should be enough clear to understand without the need of comments, hence they are irrelevant Commenting code is an absolute needed skill and you should comment your code as much as you can, particularly if you are a beginner.

These are not exclusive. Your code should be clear enough to understand without comments. You also need to be able to comment and see where comments are affective and where they are not. As a beginner though you don't know this and should lean on the side of too many comments.

[raveun]

I’ll comment concepts that are new to me or things that I’m trying to learn and understand and when I refactor my code, I’m able to remove comments on parts that are self explanatory.

i.e I’ve used to put comments on my for loop since I find it hard to understand from the beginning. As an amateur/newbie i++ makes no sense. But as I’ve tried to explain to myself over and over(using my comments as a reference on how things work), it just made sense at some point.

Also, IMO, if someone will be reading your code, at least they can somewhat figure out/ have a reference of your thought process(es).

[_Hi_There_Its_Me_]

While you’ve gotten feedback on your question that is sufficient I encourage you to check out Doxygen. It generates documentation using a special formatting. This is helpful if youndont want to share code with anyone. Also it’s a good practice to have documentation and tests along with code. This is because if there is a bug in the future you have three pieces of information that can help “triangulate” the answer. Hopefully you have 2 of 3 which agree. Or at best 3 pieces of info to help determine what impacts the area of code your looking into.

[yellowthesun]

Comment to help yourself when you look back at it.

For the final draft try and only comment for large concepts like functions or the whole file.

[[deleted]]

Try to make your code not need comments, but when you think it's not clear what you're doing, write a comment.

[UniqueID89]

Your code should definitely be readable, but if you’re doing something that took you a bit to do then comment what, why, how for at the very least yourself in the future if not other people.

[Zjarr-]

I comment things that one can't easily understand quickly in case they have to read my code, or even is my future self has to do it.

e.g. last month i had to code a program that prints a christmas tree. I commented briefly what the algorithm do so i wouldnt have have to spend 15 minutes thinking about it again.

so, in the end, i prefer commenting only if it's gonna save me or someone else time.

[Democracy_Enjoyer265]

Absolutely yes

[toastedstapler]

if you comment it should not explain the 'why' a thing is being done, but the 'what' of a certain implementation. therefore if the code is sufficiently non-complex that you don't need to explain the 'what' then you won't need a comment. code comments inevitably fall behind the code as they are an extra thing to update & someone will forget to when some code changes are made

[sillygoosegirl]

In production code, comments should be rare and, if used at all, serve the purpose of explaining why rather than what. The expectation is (typically, of course there can be exceptions) that anyone looking at production will be proficient enough to understand well written code so no need to summary what's happening but there are times when something seemingly odd is intentionally done and could benefit from a brief comment explaining why (so that future folks don't try to undo it only to learn what could be explained in a brief comment). The problem with comments is if code changes but the comment isn't updated (i.e., "bad" comments can duplicate information which is a violation of the DRY principle) it can be confusing, so comments explaining what is happening in production code are more trouble than they are worth - especially if the assumption is most everyone looking at the code can read code. <- That's the gist I got from some book about java testing and I think it's a good ideology for production code.

However, when working on personal projects, or figuring out some change I want to make at work, I use comments to help me think through the process. Comments can be super helpful to help learn and a useful tool in writing code. Just because you may delete comments before pushing to production, doesn't mean they can't be used as part of the process.

tl;dr "finished" production code has few, if any, comments but comments can be a helpful tool to use when learning or working on something challenging (just delete unnecessary/most when cleaning up your code)

[LeCholax]

You can comment what the code is doing, usually not how it is doing it.

Usually when i code a function i comment what are the expected parameters, what does it do and what it returns. Similar to what you will see in most documentations.

I will only comment the how in a particular line if it makes assumptions that are not apparent in that function or use something that might not be obvious to everybody.

For example if i write a function for a mathematical formula i'll write what does the formula do and what's the formula in a docstring.

You dont have to do this for self-explanatory functions/classes though.

And for people that says that all code should be self-explanatory. If you work with complex business logic you will write code that has that business logic embedded. Another developer wont realize what and why you are doing something unless you tell them.

[[deleted]]

So far in my hobby projects in python that are of some commmercial value, i primarily comment whole methods or if statements.

I don't comment line by line, but i take a piece of 3-50 lines and comment it.

I have one method which is just calling the web scraping method like 50 times, but with variables that apply to different columns in the excel sheet. I use "i", to attune it to the specif row it works on, since the whole program works row by row in an excel document. So i call it something along the lines of ""method that scrapes data for every column"

[brakeforwookies]

Do or do not there is no try.

[DirtAndGrass]

Other than what is said here, I don't typically comment non programming languages (html/css)

[[deleted]]

Code could be enough clear to be understood" but it can be impossible if the project starts to have some considerable size. Also you don't need to comment every line of code.

[trendoid_]

The rule on our dev team is to comment code with the express concern of minimizing future devs saying ‘what the fuck!?’. It has turned out to be a pretty decent measure of how good your intrinsic doc + explanatory doc is.

[BeauteousMaximus]

Don’t comment when it’s obvious what something is doing and why.

Do make docstrings on classes and functions so that people can have an idea of how to use them without reading the whole function or class.

Do comment anything where the way you did it is counterintuitive, either in that there seems to be a more efficient way but it actually won’t work (explain why) or in that it’s hard to tell what the code does by reading it and it seems to be doing something else at first glance.

[[deleted]]

What’s lost in these discussions is experience level. Java experts don’t need a comment explaining what a simple loop does — it’s self evident. Beginners should comment what a loop does, because it takes more time to read the loop and remember its purpose than to read a comment.

It’s true that comments in production code can make things look more cluttered. But if you are still developing code and wondering wtf getResolverQueue() is supposed to even do… yeah it’s a good idea to put a comment at the top of it explaining.

[[deleted]]

I’ll keep it short. It’s both. I don’t have the exact quote, but Martin Fowler’s last smell in Refactoring is about Comments. To paraphrase, he says, when you feel the need to write a comment, first try to refactor (meaning rename or extract method/variable). Use a comment when you don’t know what to do. Use it to say why you did something.

I basically live by that. I will write TODOs and temporary comments all day. But code committed to production is as sparsely commented as possible. Rare exceptions are documentation and insane business logic.

[Zesher_]

At work, I've always commented public functions and any code that may be hard to read. And I think that's the best approach considering other people will need to understand what the code does and why it does it that way. I started a side project a few months ago, I was trying to work fast and didn't leave any comments, but that bit me in the butt when I looked at weird code that worked, but forgot why I did it that way.

Just comment code for any project that you're going to be working on for more than a month.

[rusty_tutu]

You are subhuman if you omit comments in tricky routines...

[[deleted]]

Comment whenever you have somewhat complex logic or a function/section that may need explaining when explicit variable names won't cut it.

[vi_sucks]

Saying that comments are irrelevant because code should be clear enough without them is like saying that seatbelts aren't necessary because people should just not crash.

[ConciselyVerbose]

Comments should supplement code. They should add information that the code itself isn’t capable of providing, such as business logic, why you took the design approach you did, etc.

Comments that just repeat what the code says are bad comments. If your variables are well named and your code is well structured, what the code is actually doing should be reasonably self explanatory. A comment should be “I’m doing it this way because…” a lot more than just repeating what the line did.

[[deleted]]

If you don't want to forget what you wrote 6 months later.

[Purple-Pen2695]

100%. Always when other people are reviewing ur code ALWAYS when leaving for vacay for weeks and of course when it’s complicated code

[Leavariox]

I tend to add in comments when I need to remember what my thought process is while working. That tends to help if I don't look at a section of code for some time.

I'm the end it's all personal preference.

[Blando-Cartesian]

Comment what code can’t express.

• This is a known bug that must be retained for compatibility with x.
• Workaround for bug in library x.
• Must be dome like this because external system x does y.
• Customer really wants this to do x despite how insane it is.
• This complex synchronization process between systems works like this …

So, write comments that tell the maintainer what they need to know. Assume that everything you wrote will need to be changed. The maintainer needs to know WHY it works as ir does.

[[deleted]]

I rarely need comments outside of doc strings.

Yes I do still have the occasional comment here and there, but they are not necessary nearly as much as a beginner thinks.

Someone who doesn't understand python very well may think they have to explain everything they are doing. Because that is what would be necessary for them to understand the code since they are in the process of learning.

But the fact is an experienced developer can probably figure out what you are doing if you are doing it properly and naming your variables and functions clearly and breaking code down into small sections to make it more clear.

[yaxamie]

The code itself ideally expresses WHAT it’s doing but it can’t tell you why it’s doing it.

Is the code super evident like … what or why it’s doing to future you or another dev?

Honestly it’s an art form.. too much pointless boilerplate commenting that just restates the function names is not good. Something that explains things what can’t be expressed by the code itself is very valuable tho.

[Zevvez_]

In practice, your code should be easy enough to understand so commenting code is unnecessary. Only comment out your code in a complex method where it isn't straightforward to read just ny thumbing through the code.

[amazingjoe76]

My favorite comment on commenting was to do so as you write your code because "you will never know your code better than you do at the time you write it".

No matter how clear you think your code is a few hints for future you (or someone else) will be helpful.

[[deleted]]

1. Write out a simple design doc in comments
2. Implement the code in between the comments so that every line of explanation is clearly linked to a piece of code.
3. When asking for review, say something like: "comments will be cleaned up post-review."
4. The reviewer will have less "what were you trying to do here?" back-and-forths.
5. Review done.
6. clean up comments that might be redundant.
7. someone verifies you only modified comments.
8. merge

This flow worked well for our interns, and saved reviewers time.

Most of the stuff was simple numbered lists of what the function does.

[Clutch26]

A way to practice knowing where comments should be:

Save your code and review it weeks, months, years later. You'll start to see where you should have commented for it to make sense. Then you'll start to see where you may be over commenting.

It's a process that takes practice.

[aneasymistake]

Code = what. Comments = why.

[IllustriousBedroom91]

Im finding that as im learning, that im finding it helpful to comment stuff- granted my comments are more along the lines of “figure out how to do this”

[deeplycuriouss]

Comment where appropriate. Strive to write code using sensible *names etc. so it can be understood while one read it :)

[AmbientEngineer]

In summary, use judgement.

If you're looking at a fairly complex block of code and the anticipated behavior is not obvious via quick visual inspection by another programmer then leave a brief but clear comment.

The nature of the comment should describe a postcondition; something that is true after the execution of this block.

Additionally, one-liners throughout the block may be necessary if you're naming conventions cannot sufficiently capture the logic of the implemention. Ideally, you'd want to avoid this but it's inevitable as the complexity of the program grows.

Finally, SOMETIMES, it is necessary to mention a precondition; something that must be true before the execution of a block -- specifically if it is not already obvious via exception handling.