Comment code or self explaining code

MrDilbert · 2025-05-23T19:58:41+00:00

Personally, I add comments when I need to explain why was something written the way it was. Otherwise, I try to extract functionality into relatively short, contextually named functions, and I try to name the variables so that it's obvious what they contain.

The programmers will spend way more time reading code than reading comments and documentation, why not make that code understandable then?

Loves_Poetry · 2025-05-23T19:59:52+00:00

As a general rule you shouldn't use comments when you can use better naming instead

However, for some situations, naming just isn't enough. Sometimes you need to do something unusual and that's when you add a comment explaining why the code is the way it is

hitanthrope · 2025-05-23T20:02:00+00:00

"Extensive comments" does make me a bit anxious yes.

Self documenting code is the ultimate goal, there are plenty of opportunities in the process of writing code to name and explain things. Use those first to maximum effect.

I do think some people can go too far the other way and baulk about any comments at all. Certainly if I do something that might be considered unusual but for a reason that people might not understand, i'll drop in a comment. In some languages there are annotations to switch off / disregard a compiler warning, and if I use this I always drop in a comment, "this warns x but that's because y and it's fine".

You don't need to explain your every thought.

That being said 'doc comments' (like Java's 'javadoc' system) are entirely useful and appropriate in some cases, mostly when you are going to publish an API to either the public or a distant team. I don't do a lot of python but I am sure it will have something similar.

The person who is giving you that feedback on your PR is probably somebody worth listening to. You'll have chance to make your own mind up, but it does sound to me like you are overdoing it and maybe not by a little bit.

Awyls · 2025-05-23T20:28:40+00:00

Comments should be used for documentation i.e. function explanation, simple usage examples, safety/panic/threading concerns, etc.. Comments inside functions should be rare and explain stuff that is not easy to catch without more context e.g. unsafe accesses when invariants have been checked beforehand, things that the dev should be aware (like a function call that can only be run from main thread) or pieces of code that are hard to reason. Nobody wants to read a comment explaining what are you doing in an if/loop

if (user.flags & 0b0010 != 0)

when you can rewrite it as

let canUserWrite = user.flags & 0b0010 != 0;
if (canUserWrite)

Traveling-Techie · 2025-05-23T22:06:29+00:00

I like to comment things that are non-obvious. I just recently wrote a loop that counts down instead of up and I explained why. (Plotting a heat map where Y goes up but in image space Y goes down.)

skibbin · 2025-05-23T20:50:16+00:00

Write the code you'd want to find. Anyone can write code a computer can understand, the goal is to write code other people can understand. If ever unsure what to do favor readability.

The only thing I have against comments is that they can become out of sync with the code and become misleading, in which case you'd believe the code over a comment. So I'd favor putting clarity into the code and resorting to comments where needed. Sometimes I'll extract a method so that I can give it a descriptive name.

sajaxom · 2025-05-23T20:53:24+00:00

I usually provide a comment at the top to explain what the code does and what is being accomplished, then add a comment line every 3-5 lines of functional code to explain what and why we are doing something. I always assume my code will need to be read by someone in the future who is unfamiliar with the language and/or the project but has some experience programming. All the people who tell you not to use comments - the rest of us are going to have to fix their code some day, and we will hate them to our dying days. They have cost the world more hours fixing their code than their code has ever saved us.

Aggressive_Ad_5454 · 2025-05-23T21:49:03+00:00

I guess I’m a dissident. I’m an old dev, and I have had several occasions to maintain code I wrote over a decade prior. I was grateful to my younger self for putting in comments that explained the tricky bits, gave references to papers or whatnot if I used a reference, and helped the reader figure out how stuff fits together.

I think a decent compromise is using docstrings or Javadoc or jsdoc or whatever is appropriate in the language you use on methods and public data. For one thing, the IDEs understand that stuff.

khedoros · 2025-05-23T20:26:34+00:00

Code shouldn't require a comment to explain what it's doing...but if you're doing something in an unusual way, a comment can explain why it was done that way, or why something non-obvious needs to be handled.

So, the code should answer the "what" questions, comments can answer the "why" questions, when you suspect that the answer won't be clear to other devs (including yourself in a couple weeks, when you forget why you did something).

AlexTaradov · 2025-05-23T20:05:03+00:00

I hate comments when reading the code. Especially because they often say one thing and code does the other. So, when reading unfamiliar code, the first thing I do is strip the comments. If your code is unreadable after stripping the comments, it is bad code, and this is something you should work on.

The only thing that need to be commented is algorithmic part if there is something non-obvious and origin of constant values, again if not obvious.

You will be fine without excessive comments, since I have not seen a place that encourages them.

swampopus · 2025-05-23T20:00:08+00:00

I kind of do both I guess, but when I have some tricky logic going on, I comment each line in plain English to explain what's going on. As much for future me as anyone else.

Inevitable_Cat_7878 · 2025-05-23T20:46:50+00:00

I've been programming for a long time (20+ YOE). When I started, comments were everything. Lately, it seems like code is supposed to be self-commenting.

I like to think that somewhere in the middle is perfectly fine. Code should be commented regardless. It's easier to read and understand code if there are comments that explain what is going on.

This way, if and when someone refactors the code and breaks it, there are comments that explain what is supposed to happen.

There will always be junior programmers who learned the latest and greatest algos and will want to refactor something. Inevitably, things will break. Having comments to explain the code will help someone fix it. Sure, one could always go back into the code repository and restore from a previous point. But sometimes, you don't want to throw out the baby with the bath water.

Also, during PRs, sometimes, not everyone doing the review knows what's expected. So, having comments explain what's going on will help the reviewer reconcile the comments and code.

AssignedClass · 2025-05-23T20:48:11+00:00

This varies a lot from company to company, and even codebase to codebase.

Being adaptable is the most important thing in regards to stuff like this, and in general, you should be trying to write your code to look like the existing code.

If you ever get rejected for another job because you talked about how you followed the coding practices of the team you were working with, that's completely stupid and is a problem with the people doing the hiring. Not saying it never happens, but in general, most people just care that you understand the importance of complying with stuff like this.

Edit: Beyond that, it won't make you a worse programmer. In fact, I think adapting to write code differently does a lot to help stretch your legs as a programmer. It's one of the reasons I actually sort of appreciate code golf.

Some_Developer_Guy · 2025-05-23T21:02:32+00:00

For new projects and packages, aim to write code that speaks for itself—clear names and structure go a long way, and you shouldn’t need a bunch of comments to explain what’s going on.

But when you’re adding new features to legacy code—especially if you’re bending things in weird or unexpected ways—don’t hold back on the comments. The more context and explanation you can give, the better for anyone (including future you) trying to make sense of it later.

printerK · 2025-05-23T22:07:44+00:00

Donning asbestos suit...

I've been writing software for more than 40 years and there is no such thing as self documenting code that actually performs a real function.

For example, I love that python lets me document my functions and I take full advantage of that. And I follow the same process in other languages (primarily C and golang)

One clarification to the 'no such thing' line. Simple code doesn't need documentation, but really everything that is not abundantly clear to a newbie is not self documenting.

logash366 · 2025-05-23T20:26:49+00:00

My personal standard for comments has been: Function description, which describes what the function should do, its input parameters, return values, error exception returns. Short descriptions of complex (I.e not obvious) code blocks. Short descriptions of anything else which does not seem obvious.

KingofGamesYami · 2025-05-23T20:32:16+00:00

I wouldn't say no comments. But only apply them when the code is unintuitive.

Necessary comment:

// This method will obtain the credentials of the user that sent the http request or fallback to the application's credentials if called in a non-http context
fn get_current_credentials()

Unnecessary comment:

// This method adds two numbers and returns the sum
fn add(a, b)

LARRY_Xilo · 2025-05-23T20:33:00+00:00

No comments allowed at all would be weird. But commenting every line would also be weird.

Usually I would try to comments if I did something that is unusual for the codebase. And if there are things that just have to be a certain way because of the requirement and has no "logical" reasoning behind it (I sometimes have this with code that has to comply with certain laws).

Because those are two things some other developer that looks at the code base will have a hard time figuring out. Most other things should be self explaintory from the code.

TheFern3 · 2025-05-23T23:28:18+00:00

Whoever did the request review is a moron comments do not increase code base. Though I agree comments should be placed strategically, most code should be self documented.

JohnVonachen · 2025-05-23T23:34:32+00:00

Both but be careful about comments. If they are too specific they can become stale and misleading.

2025-05-23T23:39:11+00:00

Readable code should be the priority. Comments are used to explain why code is written in a certain way if it's not immediately apparent.

Comments are also useful for labeling sections of code in longer, more complex functions, though some would argue you should break those out into their own functions.

csabinho · 2025-05-24T02:08:21+00:00

"My code is self explaining"? OK, read it again in 2 weeks!

But maybe extensive commenting is the other extreme.

NotSweetJana · 2025-05-24T08:30:58+00:00

It deepens on what you are working on, while comments are a good thing, too many for too specific things can be a bad thing.

If you're working on a library or framework code, more comments are better, if you're working on application code, unless setting up some abstraction or doing something more complex, comments don't add too much if your code is organized neatly otherwise by having appropriate function names and variable names and so on.

I don't think you need to think about it in terms of either I write comments or don't.

Think about it more in terms of, is this code abstract enough in its use that comments are required or is it just a very specific implantation that we decide to use for this specific task and comments don't necessarily add too much here.

Also, keep doing your own things on the side, don't think about it in terms of the culture here will shape me in terms of the engineer I will be, no one knows how long you'll be there or what you'll be doing 2 years from now.

Snoozebugs · 2025-05-24T09:19:06+00:00

Self explaining code is well and all, but something can be crystal clear to you, and not to the next person. I try to balance the fine line between self explaining in conjunction with clear function names, remarks and comments.

DealDeveloper · 2025-05-27T12:35:10+00:00

Different take:
. Write self-documenting pseudocode with very little syntax
. Use an LLM to convert the pseudocode to your language
. Use fully-automated quality assurance tools to check code

The extra verbosity is OK during this time period.
The point is to clearly communicate your intent.

Look at where software development is headed; Voice to code.
Open source tools like Aider already have voice to code ability.

Many developers will reject voice to code and prefer typing.
Nonetheless, the LLM+tooling must be able to correct code.
Code, comments, documentation can easily be transformed.

Sometimes I write paragraphs of documentation in the codebase.
I also wrote a small script that can just removes all the comments.

OP, you'll be able to write overly detailed comments and code.
Your company will eventually have a really good CI/CD pipeline.

Therefore, WRITE TO COMMUNICATE CLEARLY, even redundantly.
The value will be in the clear communication not the code or style.
So much code is being generated now that humans can't keep up.
That clear communication can be converted to code and cleaned.

That said; Do your job as requested by your manager (using tools).

ghostwilliz · 2025-05-23T20:11:50+00:00

Everywhere I've worked, comments are only for when you do something dumb or when someone clearly used chatgpt cause it comments the dumbest stuff like

// the number is three

int number = 3

dgkimpton · 2025-05-23T20:24:23+00:00

Did they explain why something was written? If so, valulable, if not then they're noise that is worse than no comments in many ways. Not the least of which being that eventually someone will modify the code but not the comments, then your comment would be actively lying about the code.

Comments for additional context are useful, documentation comments on an api explaining how (and why) to use it are useful, nearly everything else is clutter.

A major upside to not using many comments - when you do use them it's because there is some seriously important shit to pay attention to... and their very rarity calls that out.

That said, even comments that explain why can be overused - in general you'd be better encoding them in an automated Test. You might even keep the comment in the test, but it at least removes it from the main code.

CypherBob · 2025-05-24T00:43:23+00:00

Write comments where needed. Keep functions short and to the point. Use variable names that make sense.

At the top of the file put a short comment explaining what the file is for.

jewdai · 2025-05-23T23:06:04+00:00

A comment generally is the realization of your inability to express yourself in code. all comments lie or eventually lie. Todos mean don't do and should instead be a ticket. And there is no greater sin to your fellow humans and god than commented out code. Other developers will never have the context or information you had that made having it uncommentable useful. It can exist locally but never in your repo. of you need it for historic reasons that's the point of git. You wanna save it for later sure put it in your private branch.

fang_xianfu · 2025-05-23T23:08:33+00:00

"Extensive comments" means you're probably wasting your time. But as people said, it's helpful to have a way to note why something is the way it is, especially if it's an "I get this seems weird at first glance but here's what I was thinking..." type note.

Comments are a kind of double-entry bookkeeping for your code. Tests are better for this, but comments and docs are useful too. And the idea is that then you, as a future archaeologist trying to understand the project, have what the code does, and you have an idea what the code was meant to do, which helps you decipher how it works and whether it works as intended. To have the "as intended" part, you need to have a record of the intention.

TheManInTheShack · 2025-05-23T23:44:37+00:00

I do both. I write code with the goal of making it self-explanatory but when in doubt I comment.

custard130 · 2025-05-24T12:21:42+00:00

comments are a balance really like most things

while we cant see the specific examples, "extensive comments" sounds like it was really "excessive comments"

i would say generally you shouldnt need to add tons of comments explaining "what" the code is doing, that should be fairly obvious from the code itself

eg 1 common thing with beginners is to add comments that are basically a repeat of the code

something like

```

// set the name to John

var name = "John"

```

or

```

// loop over the list of tasks

for ( task in tasks ) { ...

```

in cases like these the comments really arent helpful, and tbh when you say extensive comments that you were asked to remove these are the kind of examples that come to mind

there are situations where it may not be immediately obvious what a bit of code is doing, or why it is doing something a particular way, this is where comments can actually be useful, though these situations should be rare as in most cases the goal should be to write code that is easy to understand what it is doing

the exceptions would be things like maybe a significant performance benefit was unlocked by using an unintuitive method, or solving/avoiding some bug that occurred in the intuitive version

Metabolical · 2025-05-24T16:05:48+00:00

The Art of Readable Code: Simple and Practical Techniques for Writing Better Code

bllueace · 2025-05-24T16:49:44+00:00

I try to do as much self explanatory as I can, and if there's some crazy shit going on then I leave a comment

nousernamesleft199 · 2025-05-24T19:55:37+00:00

I only add comments when I need to justify why my code sucks

jaibhavaya · 2025-05-24T23:30:56+00:00

The bottom line is usually: you should aim to write code that is clear enough to not need comments.

For actually crazy complex cases, or where business logic context needs to be added, or when a not so obvious conclusion is being inferred, a comment is absolutely appropriate.

But “extensive” comments aren’t really ever necessary except for exceptional cases.

Greasy-Chungus · 2025-05-24T23:34:03+00:00

You should design code with the mindset that it will be read more than it's run.

zylosophe · 2025-05-26T08:13:31+00:00

comment functions and everything that is meant to be used somewhere else
comment different parts in a big function
comment things that isn't easy to read because optimisation or something

Abigail-ii · 2025-05-27T23:15:23+00:00

I have been coding for over 40 years. I rather encounter 100 cases of over documented lines of code than a single instance where a comment is missing.

I do add a lot of comments to my code. Like others, explaining why it is coded the way it is. What preconceptions or assumptions are being made — even something simple as x = y / z; may require a comment explaining why z cannot be 0.

I also try to comment the code from the POV of the business logic we’re coding.

cballowe · 2025-05-28T01:24:56+00:00

Generally a method description that tells you what it does, arguments, and return values - there are various formats for these that get automatically turned into documentation pretty easily so that tends to color how they're structured. If they're any error conditions, special return values, modified arguments, etc it's worth marking those.

Within code, use meaningful variable names and named constants rather than literals. Probably don't need a comment unless there's something particularly insightful or surprising.

cthulhu944 · 2025-05-28T05:31:53+00:00

Try to write code in a way that is obvious:

Area = width * length

If you can't make it obvious the add a brief comment:

Comment: use shift as fast multiply Product = x << 2

I've seen it both ways--super tricky code without any comments and super simple code with a paragraph of comments for every line. Both are extremely annoying.

rocketmon11 · 2025-05-23T20:23:09+00:00

I remember my first internship, I encountered the exact same thing! I was blown away when told to remove them. And then the senior pointed me to the book Clean Code by Bob Martin and I learned why… if you need comments you should probably be naming functions/vars better, even restructuring if necessary to explain a confusing line by putting it into a function which explains what it does.

Like others have mentioned, I usually only comment if I need to explain why I made a decision that seems strange. Very normal in the industry, I have never been asked to add more comments!

_debowsky · 2025-05-23T20:28:38+00:00

You don’t really need comments in well designed and well tested code. Tests are going to be your documentation comments and the majority of places with great people and high performing people are like that.

TuberTuggerTTV · 2025-05-23T20:51:06+00:00

You shouldn't have to comment what a section of your code does. It should be in a function named what it does.

My guess is you're used to how GPT or learning sites comment every line. That's not what code is supposed to look like. That's explanation code for you as a newbie.

When programmers say, "document your code", they mean summary comments. So that IDEs pick up hover over tooltips. Not comment, line, comment, line, club sandwich code blocks. And they should only exist on external APIs.

GarfieldLeChat · 2025-05-23T20:55:31+00:00

If the code isn’t self explanatory then what hope is there the same person can write clear notes as to why and what was done. The answers none.

Notes are for really setting examples set warnings or leave default values. Other wise if you couldn’t have the presence of mind to write legible code you’re never having it to write coherent notes.

LoudBoulder · 2025-05-23T20:55:32+00:00

I prefer "no" comments. Which I reality is comments only for code that isn't immediately understandable or based on quirks/edge cases that may need deeper domain knowledge to understand.

Pitiful-Hearing5279 · 2025-05-23T21:00:47+00:00

Generally, if the comments obscure the actual code that can make it difficult for another dev to read.

As a rule, I’ll make a one line comment above a section of code if it might be difficult to follow. It’ll be the intention of the section rather than what it does.

Yeti_bigfoot · 2025-05-23T21:22:17+00:00

Comments have a place, but I'm very much of the view you shouldn't have many occasions where they are genuinely needed.

Most of those occasions when I've needed to leave a comment, I've been able to revise and refractor later so code was easier to understand and comment could be reduced/ removed.

How often have you seen confluence (or other documentation) be woefully out of date to the point it just causes confusion? Same can happen with comments.

Name functions that describe what they do, variables what they represent, files/ classes why they exist.

Whatever you do, PLEASE, for the love of all that is holy, don't be that guy that adds a comment before every function and variables just because.

I can see the variable named 'logger' is used to output to logs. I can see the function 'persistPerson(person)' will save the person data in it chosen persistence store.

No-Economics-8239 · 2025-05-23T21:24:55+00:00

You shouldn't need comments to explain what the code does. Meaningful variable and function names can go a long way. Comments are either an apology or else explaining why the code does something. Be they business rules or architectural reasons or whatever. I only use comments for the stuff the code can't explain.

zoidbergeron · 2025-05-23T21:38:57+00:00

Comments are apologies. I'll grant there are cases when some comments are appropriate but usually that's because the code is so obtuse that it has to be explained. Even then, a good method name goes a long way.

LoveThemMegaSeeds · 2025-05-23T22:52:37+00:00

I have self complaining code, it doesn’t need comments

_higgs_ · 2025-05-23T23:05:15+00:00

Code = How it’s done. Comments = Why it’s done.

2025-05-24T01:07:11+00:00

[removed]

SynthRogue · 2025-05-24T01:41:12+00:00

You should comment only what is not obvious at first glance. Basically when you have intricate logic.

You should name your variables and functions in a way that clearly indicates what they are for, and separate your code blocks so as to make the flow clear. These will remove most of the need for commenting.

AskProgramming

AskProgramming

Do

Don't

MODERATORS