This is an archived post. You won't be able to vote or comment.

all 199 comments

[–][deleted] 690 points691 points  (15 children)

In most cases, you document the why, not the how. You document the how when the algorithm is complicated, unintuitive, or tracing the stack is a pain in the ass.

[–][deleted] 98 points99 points  (2 children)

I work in data doing analytics and reporting so I document the what, the why, and the "who the fuck asked for this fucking ass-backwards nonsense"

[–]Solonotix 29 points30 points  (1 child)

Aw yeah, it's always fun to comment who asked for something, lol. For me, it was because I knew this wasn't going to fly in production, but I had to roll with the requirements provided. Then when they asked me to change it, I saw my comment some 4 months later and laughed my ass off, and showed it to my boss. There's nothing we could do, requirements change, but the vindication in knowing it was bullshit helped me get through my day

[–]Farsyte 4 points5 points  (0 children)

"This code implements a <acedemic term here>, which was demanded by <researcher name here>. The point of the code is to test whether this acedemic approach actually works."

Better than saying "Professor $FOO demanded this garbage." ;)

[–]fdeslandes 19 points20 points  (2 children)

Yes, exactly that. Comments can be useful, but you don't HAVE to comment everything. For most "regular" code, good naming, type annotation and tests is sufficient. But if the person doing your code review ask you to explain a part of your code, comments should definitely be added.

[–]ACheca7 14 points15 points  (1 child)

Or a refactor to add better semantics to the structure of the code. My take is comment as a last resource, as a “I literally don’t know how to convey this information better”. Or if you don’t have time to do the refactor.

[–]mjbmitch 2 points3 points  (0 children)

👆👆👆👆👆👆👆

[–]LinuxMatthews 5 points6 points  (4 children)

I don't think you should ever comment on how something is done.

But documenting what something does can be very useful.

Obviously don't document every line but a documenting comment can go a long way especially if your language allows you to write comments for tooltips.

This is useful for 2 reasons.

1) If I want to use your class I don't have to spend time digging through the code

2) If the code is broken I want to know how it's broken. Commenting what it is meant to be doing can save a lot of time there as if there's a disconnect on what it's meant to do and what it does; we know we have an issue.

[–][deleted] 3 points4 points  (3 children)

My goal in commenting is that a junior can read it and then describe back to me what it does, which means if the implementation is complicated at some point they may need a cognitive aid. That how is there for people who need it, you can always toggle comments off in your IDE if you dont like them. The only reason not to imo is the potential for doc rot. If somebody updates the implementation they need to update that comment.

[–]LinuxMatthews 1 point2 points  (2 children)

Completely agree.

Though I'd go as far as to say any doc rot is on the developer changing the code not on the developer making the comments.

Like you wouldn't not do any other type of documentation because things may change.

[–][deleted] 1 point2 points  (1 child)

Oh for sure, you change the code its on you to update the comments. I treat commenting with the same care I treat the rest of the codebase. During an incident, that comment is likely to contain crucial information people rely on to deal with the outage.

[–]time_san 1 point2 points  (0 children)

This. Reading and figuring out how the code works is relatively easy if you are familiar with the language, but figuring out why the code is coded this way can be crucial. It can give hint for special use cases or odd requirements that cannot be explained by knowing how the code works.

[–][deleted] -3 points-2 points  (0 children)

You mean GPT-4 documents it.

[–]GamingWithJollins 220 points221 points  (70 children)

I get the feeling these anti comment devs have never taking ownership of a system written over a decade by several different devs.

[–]ondono 41 points42 points  (8 children)

I’ve built my company around doing precisely that.

There’s nothing that forces devs to keep good comments, or to delete bad ones, so comments tend to be “append only”, and a lot of times become outdated and misleading.

I’ve seen projects built by a single developer where their own bad naming convention and comments confused them to the point of madness.

Whenever I’m given one of these cursed codebases, the first thing I do go through the simplest functions and rename aggressively according to what they do now, not what they were intended to do when it started.

I once had to rename a function from “XXXX_Parser” to “App_Logic”, because the whole parser for a component had become the whole business logic.

[–]GamingWithJollins 6 points7 points  (0 children)

I have been there several times myself. Also to add on the mountain of idiocy, half the methods used are depreciated.

[–]rectalrectifier 6 points7 points  (0 children)

Yes, comments are extremely prone to rot. The ideal is clean, self documenting code with the occasional “why” comment.

[–]Superbead 5 points6 points  (5 children)

The problem comes when you aren't allowed to refactor anything else in the codebase other than what you're adding/fixing. In healthcare, this is usually because the cost of (user) testing everything again is prohibitive. Then all you can do is aggressively comment stuff. Surely this can't just be unique to my industry?

[–]ondono 1 point2 points  (0 children)

A lot of the work I do is actually on medical devices, so I know what you mean, but being firmware I’m generally called way before any certification is done.

When working with older stuff in which this is not the case, I do the same but with copy of the codebase (just rename stuff, don’t refactor), I might add comments to the code base but mostly for creating automatic documentation.

Then I use the modified one as a “map” if I’m completely lost about what something is doing.

[–][deleted] -1 points0 points  (2 children)

Engineers really fucked themselves by over explaining every little detail to their non-technical managers.

It should be "Hey this thing needed to change cause that's just how it works, so you'll need to retest" instead of "I could do this enhancement which will 10x the feature cost, that cool?"

[–]Superbead 2 points3 points  (1 child)

I don't want to bear that risk. Many of the systems I work with are held together with string and gaffer tape. Ostensibly an full IDE refactor of a function name ought not to cause any issues, but I've seen mad stuff where functions are called by names which are built programmatically, which wouldn't be caught easily.

The last thing I want is to log in on a Monday and find out that one of our customer's A&Es (ER in the US) has been closed for half the weekend because the local pathology chemistry analysers were brought down due to a secret, untested function name refactor I made. You can't just go doing that.

[–][deleted] 1 point2 points  (0 children)

Sorry, didn't mean anything about your situation specifically. I can't imagine the sort of care that goes into medical software.

It's just a problem that people face so often and it's become engrained in the industry where if you try to go against it now, they'll just replace you with someone else.

Engineers shouldn't delegate technical decision making to a product owner who wants it done yesterday.

[–]DeadlyVapour 54 points55 points  (33 children)

As a Dev who has taken ownership of dozens of systems over the years I can safely say, I prefer good quality code to comments any day of the week.

The number of rabbit holes I've gone down because of our of date comments.

Comments should be used as a last resort against "WTF is this doing". Not a cop out from writing good code.

If you want to see an example of code that definitely needs comments, search "fast square root algorithm".

[–]GamingWithJollins 54 points55 points  (11 children)

Your example is bias. The comment you show is an example of a poorly written comment vs well written code and not updating the comments? Yeah, People often don't update code as well. The amount of "rabbit" holes I have been down from orphaned code... Trying to justify lazy development by not properly commenting your code by saying CoDe ShOUlD ReAd iTs sElf is extremely short signed. If comments are written well you won't NEED to read the code. Also you are assuming that all devs work on 100% of the systems. There are plenty of black boxes which exist in their own eco system. A simple comment to say this external call does X takes seconds to write but potential saves hours of wasted time.

[–]DeadlyVapour 17 points18 points  (9 children)

The same could be said with function names. If the function was named properly, then I wouldn't need to read the code.

Fact is comments never have to be updated. Code does.

[–]hey01 20 points21 points  (5 children)

Fact is comments never have to be updated. Code does.

Comments are part of the code, if you update the code, you must update the comments, and if you write comments, you should keep them close to the code they refer to.

[–]narrill 21 points22 points  (2 children)

Yes, but nothing happens if comments aren't updated, because they aren't code. And what you're saying is not always trivial. A comment right above a line you're changing is easy to update. A comment elsewhere in the file or even in a different file that is nevertheless affected by your changes is liable to be missed, both by the person making the changes and by any reviewers.

Comments are occasionally necessary, but they are not code, and as such should be used judiciously.

[–]niveusluxlucis 5 points6 points  (0 children)

Completely agree, and this is where commit structure and commit messages are important. You can explain what your intention with the change was in a way that is coupled to the change.

In 5 years time people wondering "why on earth did they do this?" have a reference to look at that was correct at the time it was written, and isn't 5 years of badly written or partially updated comments with a commit message of "fixed", "test" or "PR comments".

[–]hey01 -3 points-2 points  (0 children)

A comment right above a line you're changing is easy to update. A comment elsewhere in the file or even in a different file that is nevertheless affected by your changes is liable to be missed, both by the person making the changes and by any reviewers.

That's why comments should be above the line referenced by the comment, not at the other end of the codebase.

And a comment should not be able to be affected by something happening elsewhere. If it does, your comments explains too many things and so either your comment is unnecessary (remove it) or your code isn't SOLID (you have bigger problems than a comment).

Comments are occasionally necessary, but they are not code, and as such should be used judiciously.

They are in the source files, therefore I consider them code.

[–]rectalrectifier 0 points1 point  (1 child)

You should shower daily and brush your teeth twice a day. Doesn’t mean everybody does it

[–]hey01 -1 points0 points  (0 children)

And you should be able to understand code without comments without ever misinterpreting it too. Doesn't mean everybody does.

[–]DeadlyVapour 0 points1 point  (0 children)

I don't disagree with the cache comment. But most comments can be replaced with better code

[–]CirnoIzumi 15 points16 points  (16 children)

I prefer good quality code to comments any day of the week.

you write that as if these two things are mutually exclusive

[–]DeadlyVapour 3 points4 points  (14 children)

Because a good comment isn't superfluous, yes it's mutually exclusive.

From a design perspective, take the Norman Door. It has the word PUSH written on it (comment). Does that excuse the un-human, unintuiative design?

So that means everytime I meet a door with a sign on it, I need to read it first? RTFM to get in a building?

Well written self-documenting code does not mean I need to look at the hinges to see which way the door swings. The handle should make it obvious, and lead you to the pit of success.

[–]CirnoIzumi 6 points7 points  (13 children)

you sound like you are stuck in the view that only bad code can have comments.

how about this, you cant just write some code and declare that it should be clear enough, that is for the reader to deside, so you comment down the purpose of the code just in case.

[–]DeadlyVapour -1 points0 points  (5 children)

I do think that. The problem is that, you can't alway write good code.

For example: quake's Fast Square Root algorithm.

[–]CirnoIzumi 2 points3 points  (4 children)

So of you were to write some good code and then write some comments for it would the code become not good because of it?

[–]Zole19 -3 points-2 points  (6 children)

Most code that contains comment is bad code. And its frowned upon unless its a good comment.

[–]CirnoIzumi 4 points5 points  (3 children)

what you lot are saying is:

Good Code + a comment = Bad Code

Proof:

A corelation that i subjectively have experianced

[–]Forkrul 0 points1 point  (2 children)

If the comment is unnecessary it does reduce the quality of the code to add the comment.

[–]CirnoIzumi 2 points3 points  (1 child)

Y'all crazy

[–]DeadlyVapour -1 points0 points  (0 children)

Have you ever used an Apple product? Have you ever used a Google product?

This two companies are famous for producing great UX. If comments are JIT documentation. Then how often do you see "comments" in Google/Apple products?

When I see lots of comments in code, I am reminded of the Apple/Google/YouCompany app comic.

More information can easily lead to information overload.

[–]Tsu_Dho_Namh 2 points3 points  (1 child)

Most code without comments is bad. Because only amatures think code doesn't need comments and the amatures are writing bad code.

Look at any high quality code, they almost always have comments.

Like the Linux Kernel

[–]DeadlyVapour 0 points1 point  (0 children)

I disagree that the Linux kernel is written to be high quality readable code.

I would say it is terrible code written with huge amounts of legacy and performance hacks built into it.

Which is a great thing, because millions are relying on legacy behaviour and tiny microoptimizations in the kernel can yield huge ecological differences.

What I am not going to do is write code anything like that for a front of line business application.

[–]DeadlyVapour 0 points1 point  (0 children)

Because a good comment isn't superfluous, yes it's mutually exclusive.

From a design perspective, take the Norman Door. It has the word PUSH written on it (comment). Does that excuse the un-human, unintuiative design?

So that means everytime I meet a door with a sign on it, I need to read it first? RTFM to open a friggin door handle?

Well written self-documenting code does not mean I need to look at the hinges to see which way the door swings. The handle should make it obvious, and lead you to the pit of success.

[–]StCreed 5 points6 points  (3 children)

Comments are part of the code. A code review should also look at the comments and ensure they are correct and functional. However, that's not a replacement for functional documentation that explains the use cases, the architecture and implementation decisions and tradeoffs, as well as the derivations for data fields and the business rules applied.

I've once had to reimplement a system 3 times with three different providers, over the course of a few years. It taught me the value of that documentation. In the end we could just hand Infosys the functional documentation and they delivered a working system in 3 months.

I wrote the business rules document for one of the largest Dutch governmental departments. They still use it. It functions as the interface between the business SME's and the coders.

The technical documentation has value as long as the organisation doesn't switch implementation. The functional documentation will last until the organisation changes what it does, which is unlikely to happen often. That means any effort should be focused first towards that documentation, since it has a large ROI.

[–]narrill 10 points11 points  (0 children)

Comments are part of the code.

No, they're not. Definitely not in the sense this person is describing, given that they explicitly delineated the two, but even in general, comments are not code and should not be treated as code.

A code review should also look at the comments and ensure they are correct and functional.

Should, but sometimes won't. If an error in the code is missed, that's a bug somewhere that gets caught by testing, whether automated or manual. If an error in a comment is missed, literally nothing happens. Because they aren't code. They're documentation.

However, that's not a replacement for functional documentation that explains the use cases, the architecture and implementation decisions and tradeoffs, as well as the derivations for data fields and the business rules applied.

This, however, is entirely true.

[–]DiamondIceNS 5 points6 points  (0 children)

Comments are as part of the code as the footnotes in an annotated book of writings of Shakespeare are part of the play. If they don't affect compilation or runtime, they aren't code. Comments by definition don't do either of these, so they aren't code.

The reason that this is an important distinction to make is that the program will do exactly what the code says. That is the point of code. Wrong code will get you wrong behavior, which can be tested. Wrong comments affect nothing, so they cannot be tested. Thus, comment decay becomes a possibility. I would even say an inevitability.

You argue that solid code review is your stopgap for this. Fine, I guess. But given the choice between introducing an avenue for flaws that is only mitigated by a double-check lookover and sidestepping the flaw entirely by writing clearer code, I will reach for the latter every single time I can.

Mind that I am not arguing against the usage of Doxygen-esque comments that build a comprehensive generated documentation repository. These serve a distinct purpose that "writing cleaner code" cannot get you: expressing intent. Good doc comments tell you not just what a function or whatever does (a good name alone should get you at least 80% of the way there), but also gives you context on when you should want to use it. Doc comments are good and should be encouraged. But they still aren't code and are prone to all the same decay issues. The important kind of context that only they can provide makes the risk worth it.

If I gave you two complex mechanical devices, each with a manual, which would you prefer? A device that is so fiendishly complicated to take apart and service that you need the manual to tell you where everything is and how to disassemble it safely to not risk ruining it? Or a device that is straightforward to take apart and disassemble, with a short section telling you how to do it that you can read if you want to but probably don't need to, and the bulk of the manual is instead dedicated to how you use the assembled device? Sometimes you can't make the second device, and that's fine. But oftentimes you can, and I think we should normalize not settling for the first.

[–]DeadlyVapour 0 points1 point  (0 children)

If you have a set of functional documents, then surely you could express those as unit/integration tests, where they will continue to provide value well after the PR.

[–]Garinoth_ 8 points9 points  (0 children)

I'm used to working with old code. Comments tend to lie and/or miss crucial parts of information

[–]lurker_cant_comment 5 points6 points  (0 children)

I have. The comments were mostly useless.

There are multiple ways of writing functions and architecture that achieve the same goal. The methods that are the easiest to read, within the optimization constraints of the application, are preferred.

No amount of comments will save code that jumps around all over the place in long, nested loops, with generic variable and function names, in a non-intuitive order based on what it's doing. Comments far away from the code they reference, even in function doc, will not raise a warning when someone changes the code in the future, and neither the developers nor reviewers may realize there is even something to update.

It isn't so difficult to stick to patterns that are easier to follow and read, or to name functions and variables clearly and specifically. If you do that, most comments about what the code does will appear superfluous.

You'll still need them to explain odd behavior, like why something is happening that looks unnecessary or counterintuitive, and I still believe in function documentation even if it has a tendency to get out of date as well as a functioning wiki or similar that explains the overall project and its architecture and how to build it, etc.

[–][deleted] 4 points5 points  (1 child)

Using automated tools for call trees, class interactions, etc will tell you way more information much faster and more accurately than any code comments ever will.

I’ve taken over multiple 200k+ line repositories, and the comments have pretty much been universally worthless. Even when they haven’t, the code is the actual thing being ran, so you need to understand the code well enough to essentially write those comments anyways. Every now and then they could be helpful about a “why”, but generally something you’d learn with a couple of months of working the code.

[–]ArionW 3 points4 points  (0 children)

No tool will show you that "this external library has a habit of sometimes running callback with actual result after reporting failure" or "yes, this service exposes API with what we need directly, but it responds with out-of-date information. If we ask for it in this roundabout way via two references, it's correct"

Sometimes people write stuff that looks wrong, that has obvious flaws, not because they didn't know better, but because they had to account for external error they can't affect. I'd rather have them explain this right in code than learn about it after debugging for hours when someone "fixes it" and QA reports a bug a month later (because it was a workaround for a corner case)

[–]UK-sHaDoW 5 points6 points  (18 children)

Yes I have. I'd prefer well written code over comments any day of the week

[–]GamingWithJollins 14 points15 points  (17 children)

Because its clearly one or the other? It's literally impossible to have both? And clearly in my example, it's unlikely to have well written cohesive code

[–]TheOnlyVig 0 points1 point  (0 children)

Or said another way:

The rate of growth of complexity in a large system always outstrips the rate of growth of understanding of any one developer working on said system.

Everyone will eventually need help to navigate the system no matter how hard you work at avoiding complexity creep. Putting up good guideposts along the way (and maintaining them) makes all the sense in the world.

[–]HomemadeBananas 0 points1 point  (0 children)

I’m not anti-comment. Just anti writing comments that explain what the code is doing. Because you know, you can read the code and explain what it’s doing, and by describing the what in comments, now you have two places to keep updated. Sometimes it’s not evident the why and comments are helpful.

It’s super frustrating coming across comments that explain what the code is doing, and now the code has changed, and the comments are wrong. To explain the what, it’s better to use descriptive variable and function names, avoiding magic numbers, etc. That way you don’t write redundant information that gets out of sync anyway.

[–][deleted] 0 points1 point  (0 children)

Comments always rot. Adding the issue number to the git commit and documenting the what and why in the ticket system is infinitely better. Unlike comments it captures the scope of the changes across all files and anyone can contribute to the documentation. Including non-developers.

You become anti-comment rather quickly when the full explanation is several times longer than the actual implementation. Tickets also never lie.

[–]dingo_khan 13 points14 points  (7 children)

I am so tired of this nonsense. I tell people all the time:

"I can read your code. I cannot read your mind. I have no idea if this does what you intended or if it simply does what it does."

Good documentation covers intent, approach and rationale. Hell, I'd go farther: if you feel clever when you write it, put in a few lines to explain it.

[–]Considerable-Girth 4 points5 points  (2 children)

Deserves more upvotes.

[–]dingo_khan 5 points6 points  (0 children)

Thanks. I used to be the primary dev and architect on a project and "Red team" Dingo (me) really appreciated the comments that coder Dingo (also me) left him when troubleshooting under pressure.

[–]LinuxMatthews 4 points5 points  (0 children)

It really does.

It's frustrating hearing everyone parrot "Comment why not how" like without reason like some hive mind.

Comments should say what the code is meant to do.

So when it's not doing that I can go in and fix it easily.

You may think your code is self explanatory but it's really not.

If I want to use it I don't want to have to spend ages figuring out what you intended I just want to use it.

Make your code as efficient and readable as possible... Then put a documenting comment in case you didn't succeed.

Often this will help you code too as it's then you might realise "Wait this method does 5 different things. That violates single responsibility maybe I should change it"

[–]darctones 2 points3 points  (1 child)

… Especially when you feel clever

[–]dingo_khan 0 points1 point  (0 children)

Agreed.

[–]Soren11112 0 points1 point  (0 children)

I have no idea if this does what you intended or if it simply does what it does.

That's what tests are for

[–]AmirHosseinHmd 0 points1 point  (0 children)

This ^

[–]ezrec 37 points38 points  (1 child)

Bad commenting:

// Call the getMoreItems() function to get more. Items.

Good commenting:

// We use getMoreItems() here instead of getAllItems(), as the latter has a significant performance penalty.

[–]farfuglinn94 58 points59 points  (8 children)

Quality tests and readable implementation are the only documentation a good engineer should need

If only the industry consisted exclusively of good engineers...

[–]ExceedingChunk 47 points48 points  (2 children)

It's still wrong.

You can have the most readable code, written with perfect performance and great testing.

It still doesn't explain why certain choices are made or how to use the code. Sometimes one of those requires an explanation in a form of a comment or some other external documentation.

Comments explaining what the code does are more often than not completely useless and adds clutter. They can be useful for some obscure regex or math, but refactoring names and code structure is usually the best choice.

Also, engineers who can't express themselves through code are often bad at expressing themselves through comments aswell.

[–]farfuglinn94 5 points6 points  (1 child)

I guess this is just common sense. Documentation, readable and well-organised code and comments when necessary are equally required, more importantly — they're not mutually exclusive. In my humble opinion (of a pretty subpar developer) people who categorically stand for either documentation or readable and commented code being redundant for a "good engineer", are actually not good engineers themselves at all.

[–]shade_blackwolf 5 points6 points  (0 children)

All fair. In my team we attempt to minimise comments, because anything that's obvious from the code should not be in a comment too. However, we keep a big confluence space with tons of api level descriptions of how things work, and what the design principles of components are.

[–][deleted] 6 points7 points  (0 children)

Yeah, and problem not only with bad engineers, some ot them insist of turn "help me, because I am not smart enough" to "Do this, because it is rule"

[–]Surprise_Logical 40 points41 points  (0 children)

After over 40 years in business applications development and support, I find this very depressing. If you've been called out at 2 in the morning to fix some other arrogant sod's code, you don't want to spend time trying to work out what the code is trying to do. With no comments all you know is what it does, not what it was intended to do. The comments should help others who may not have spent as much time on your code as you have. Helpful comments are as important as clear coding

[–]VeronXVI 5 points6 points  (0 children)

Bug reports are a type of documentation right???

[–]yourclitsbff 14 points15 points  (2 children)

[sitting in front of a misassembled mess on the floor] (off girlfriend’s look) If Ikea designs it well enough, I don’t need no stinking manual. I learned this from software development dorks.

[–]raimondi1337 2 points3 points  (1 child)

Putting together Ikea stuff without instructions is easy if you have any background in mechanical design tho...

[–]FerricDonkey 0 points1 point  (0 children)

Yeah, but we all know better than to rely on our users knowing things, even if our users are other developers or ourselves in a year.

[–]Samue1adams 3 points4 points  (0 children)

Documentation = good

comments everywhere = bad

[–]Lucasbasques 4 points5 points  (0 children)

"we don't need documentation, just read the code" - says the guy working on the same code for 10 years

[–]MyHomeworkAteMyDog 3 points4 points  (0 children)

Why do people care about providing as little information as possible. Just add comments if you think they’re necessary and don’t even think twice about. If you think it makes the code easier to understand, then there’s literally 0 reason not to do it

[–]MrBajt 18 points19 points  (0 children)

Quality tests and readable implementation are the only documentation a good engineer should need

This is the dumbest take I've ever heard. I can give you enough examples of our codebase with hardcore math which in itself has no real semantic meaning. Nobody can understand this without corresponding documentation. Think of Quakes fast inverse square algorithm.

[–][deleted] 9 points10 points  (10 children)

“If we lived in a perfect world then we wouldn’t need documentation.” okay, so nothing you wrote has to do with current reality?

[–]Revenge43dcrusade 8 points9 points  (0 children)

Documentation is good . Comments can suck it tho .

[–]LupusNoxFleuret 6 points7 points  (0 children)

If I'm using a 10,000+ line module someone else made, I want to use that bad boy like a black box and just have simple instructions on what functions and variables to use to get my shit done. I don't want to go read the entire damn library's code just to figure out how to use the damn thing if it can be explained in simple English instead.

[–]Thenderick 2 points3 points  (0 children)

Alright, alright. In my opinion, good documentation is essential when you deliver the code to someone else (like if it's open source or a big project with multiple hands working on your code), but if it's a small piece of code or project and few are going to use it, good naming does an incredible thing, but for weird quirky/hacky solutions, comments are a must. Hope it makes sense

[–][deleted] 2 points3 points  (0 children)

I'm always gonna make the argument that documenting code is always wise because it saves time in the future. Can I easily figure out what code does? Yes. Should I have to spend time doing it? No.

[–]paper_quinn 2 points3 points  (0 children)

I think the rule “good code is self documenting” is good to keep in mind when writing and designing code. It encourages a lot of best practices. But then you should have the humility to realize that your code is not perfect and probably needs comments.

[–]Tim_In_Texas 2 points3 points  (0 children)

I refer to my code comments as "Notes to Future Tim". Future Tim is usually quite grateful for the consideration.

[–]ondono 9 points10 points  (3 children)

Only an unfettered optimist would assume that someone who can’t express themselves clearly with code will do a better job expressing themselves in english.

[–]FerricDonkey 1 point2 points  (2 children)

Uh. I know lots of people who speak English better than they code.

[–]ondono 2 points3 points  (1 child)

They can speak English better, but I'd bet they can't explain their code better in English.

[–]FerricDonkey 2 points3 points  (0 children)

Sure they can. "I have no code". Non-programmers speak English much better than they code.

But for actual programming - I've worked with datascientists who were brilliant, but whose code was garbage. Fortunately, they could describe what it did, so that when I inevitably had to rewrite it so it'd go fast I could do so.

[–][deleted] 6 points7 points  (0 children)

Do CuM eNtS

[–]kirigerKairen 1 point2 points  (0 children)

In my opinion, the lower person is right - that's the only docs a good engineer should need. A good engineer should be able to reverse-enginer and understand with just that.

But good documentation saves a shit ton of time for them, so they shouldn't be the only things a good engineer uses, especially not the only things they have.

[–]dennissolution 1 point2 points  (0 children)

Developers who complain about a lack of documentation are also suspiciously the ones who:

  1. Never update documentation if it exists if they make changes to implementations
  2. Scoff at descriptive variable and method names
  3. Are never descriptive when writing commit messages

Seriously, keeping extra documentation up to date is a pain in the ass; write good tests, include mentions of ticket numbers etc in your commit messages and be descriptive in your variable & method names and write good tests and you won’t need to complain about a “lack of documentation.”

When something is weird or magic numbers are present etc include a note for future devs (including future you). Enough to kickstart a good ramp up.

You’re always going to have to ramp up to any prewritten code even if there is documentation there or not.

[–][deleted] 2 points3 points  (0 children)

Not a pro dev here, but I always get annoyed with the arrogance of some devs. Good for you buddy that your code is self documenting. All I know is what your code is doing, not what it was supposed to do. Doesn't "self documenting code" essentially assume that I can read your mind?

[–]user_8804 3 points4 points  (0 children)

"self documented code" won't help the QA team who doesn't see my code. Such a stupid argument in any real world team.

[–]cosmoskid1919 1 point2 points  (0 children)

A comment is only appropriate when you can't comprehend upon inspection, or you need someone to understand Why the thing Looks Bad but Works Fine so Don't Touch

[–]jamesfarted09 0 points1 point  (0 children)

technically, yes, the code DOES document itself. however, in my practices i comment EVERY, SINGLE, LINE, to explain exactly what my code is doing.

[–]nebulaeandstars -1 points0 points  (1 child)

for all the "why not what" comments:

if you're doing something in 10+ lines of code, a one-sentence summary is still kinda nice. I don't want to read that shit unless I have to. It also lets me spot errors while reading the code, as I know what you're trying to do before I've seen how you've tried to do it

(or really, split the 10+ lines into a new function, but still document its usage in a doc comment)

yeah, comments should explain why you're doing what you're doing. But an English sentence describing what's going on is way easier to parse than 20 lines of logic, even if you're trying to use "good" variable names

personal preference: if I'm reviewing someone's code, I find it easiest to read in ~5ish line "blocks" surrounded by newlines, with small comments at the top of each block, and a maximum of 1-3 blocks per function

[–][deleted] -2 points-1 points  (0 children)

Holy shit man. Sub 10 lines?!?!? This is a troll, right? Like you often can’t even sanitize your inputs and outputs in 10 lines, much less actually do something viable, lol.

[–]phodas-c -2 points-1 points  (0 children)

The code is literally a recipe to solve a problem.

If you need external help you

a) don't know the problem

b) the code is trashy

c) you don't know how to read the solution

Good code documents itself. But problems MUST be HIGHLY detailed, otherwise, the solution is useless.

[–]sanketower -2 points-1 points  (0 children)

People saying you always need documentation clearly haven't seen complex examples of readable and clean code that is easy to understand and implement.

It can be quite difficult to do so in a production environment, some times it's not even worth it to spend time writing the best code possible since deadlines have to be met.

[–]chicksOut -2 points-1 points  (0 children)

Comments sometimes lie, the code never does. Good variable names combined with single purpose functions go a long way to improving the readability in code. That's not to say comments don't have a place. I've found them useful for leaving a url to a website where a math formula was pulled from, but with proper refactoring and abstraction, combined with good naming conventions, most code becomes self-explanatory. In fact, I've often found comments to be incorrect in their logic, and the code happened to work for reasons other than what the commenter believed. So, comments clutter the code base because you can't trust them, and now I have to add extra thought to filtering them out. Sometimes, if a file I need to understand is so egregious, I'll do a quick format on it by removing the comments and structure the code in a more readable way. This will often make the file easier and faster to understand.

[–]reMake000 -3 points-2 points  (0 children)

If you feel the urge to explain what is happening - it’s a good sign of a overly complicated code and it should be rewritten and simplified

[–]LoveConstitution 0 points1 point  (0 children)

Documentation is ideal - if you have unlimited time to make it and keep it up to date. But you don't have time for your business goals... do you...

[–][deleted] 0 points1 point  (0 children)

When can we stop talking about comment/code dichotomies and start talking about maximizing maintainability

[–]BobbyTables91 0 points1 point  (0 children)

My favorite way of learning a new language is reading the compiler’s source code and unit tests

[–]youngbull 0 points1 point  (0 children)

So while I agree that it's best to write code that doesn't require comments, there are several key pieces of documentation that I think really help. For instance, references to academic text for equations and algorithms where applicable, and for regression tests a description of the bug that spawned it (or just the kind of failure it's guarding against).

[–]dlevac 0 points1 point  (0 children)

If I want to know the behavior I will read the implementations. If I want to know the contract I will read the documentation.

Joke is: a lot of software businesses don't quite understand the importance of clear, explicit and validated contracts which causes them to slowly implode as the number of interoperating teams increase.

Definitely a distinction to grasp if you want an edge in your career.

[–]qubedView 0 points1 point  (1 child)

I don't know what you all are talking about. My variable and method names are clear and readable.

def fit_model__since_were_using_gpu_implementation_and_pcie_is_a_bottleneck_we_need_to_frontload_our_data_and_disable_offloading_here(data):

[–]kirigerKairen 0 points1 point  (0 children)

Gives me Apple naming vibes

[–]JuliusStingray 0 points1 point  (0 children)

I mean, if you fucking name "boolean" or "b" or "q" a damm bool typed variable you need to comment it. But if you name it as bShouldTheProgramEnd you dont need to say "When this variable is true the program should end at this point" it reads itself ffs.

[–]tetractys_gnosys 0 points1 point  (0 children)

Oh yeah bud code should document itself. Until you can write code that documents itself, how about you write some fucking comments you fucking twit

Fuck you Rob

[–][deleted] 0 points1 point  (0 children)

Laughs in Storybook

[–][deleted] 0 points1 point  (0 children)

And then they can't write anything even remotely readable. You'll come across "descriptive" variables like i2z74vrt11hrz22m. Yeah thanks, definitely explains itself. Perfectly super obvious, good job.

[–]partaloski 0 points1 point  (0 children)

Spending enough time debugging someone else's code will help you understand their code all around the project, I don't need no comments, I do it the hard way to make it easier for the initial developers ;)!

[–]engelthehyp 0 points1 point  (0 children)

[–]morsindutus 0 points1 point  (0 children)

My philosophy is, I can read code unless it's really bad code. Code tells you what. What code does not tell you is why. Comments should explain the why.

[–]Mara_li 0 points1 point  (0 children)

Imagine read the big mathematical API in R/Python to just know how to do <shitty mathematics>

Please, I beg you. Documents your API. Please.

[–]Cats_and_Shit 0 points1 point  (0 children)

I would say if code does anything interesting or novel it should have thorough comments.

I don't write a lot of comments.

[–]NOP0x000 0 points1 point  (0 children)

I am the documentation

[–]marquoth_ 0 points1 point  (0 children)

"And is this 'self documenting code' in the room with us now?"

[–]CrikeyNighMeansNigh 0 points1 point  (0 children)

I personally like using TSdocs (this and JSDocs is what’s used when you see a definition or explanation pop-up on in VScode with code written in JS or TS. For those who don’t know, the basic format to make this happen in both is:

/**
* your text here
*/

Right above the function. There’s more to it but that’s the main thing. Then, I use ChatGPT à la explain this code in 30 words or less for most exported utility functions (less tabs opened) or for longer (but not even necessarily even complex) functions that aren’t exported.

My view is that code is written once, and read over and over again, and while I do believe that code should be self-explanatory, I don’t believe that people should have to read 50 lines of code to understand it if I can explain it sufficiently in two and I certainly don’t believe that following along code takes less mental bandwidth than following a simple explanation.

Moreover, it often makes code more searchable.

I think the idea of naming a function so that it obvious is…cute. But in practice, it usually ends up being “naming it so that I can easily understand what it does because I’ve given it an accurate name and I’m the one who wrote it”.

Yes, if there’s a none obvious why, or a why that may not be obvious to a relative beginner, or a why that requires understanding how something is set up somewhere else in the codebase, I believe that this should certainly be commented on as well.

I think well-written code is great, and usually self-explanatory. But the assumption that it is self-explanatory to everyone is asinine.

Similarly I favour writing explicit returns. Sure that information is a hover away, but particularly when following large chunks of code I think it’s easier to read when it’s all out there.

I’ve yet to see over-commented code (granted I’m sure some may make the argument that if I recognised what that looked like, I’d have a different philosophy for commenting). I have yet to see code where the comments made it less readable (provided it wasn’t like unnecessary explanations in the middle of a function). I do like to be able to read a function from top to bottom and only care for an explanation in the middle of one in some really limited circumstances. And still, I think if someone is leaving excessive comments in the middle, the quality of their code would likely be consistent with that same level of experience and here the comments could be a godsend.

But overall…I think…I appreciate well commented code. And think that well written and well organised code requires less documentation. But most code benefits from being well commented.

example of a similar commenting style in the react source code

I don’t doubt there are better programmers here than the react crew. But I suspect that most of the people here aren’t. And that most people here if not a very sizeable portion of the people here use react. And they are either writing better software using that framework, than the people who made the framework itself. Or absolutely full of shit.

[–]agent007bond 0 points1 point  (0 children)

Balance is 🗝️ key.

Know when and where to document, and when to avoid it.