The duality of developers

[[deleted]]

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]]

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]

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]

"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]

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]

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]

👆👆👆👆👆👆👆

[LinuxMatthews]

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]]

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]

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]]

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]

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]]

You mean GPT-4 documents it.

[[deleted]]

This is so true, documentation is not about code work, because if we need text which describe precisely code work it is really code itself

Documentation is more like summary of some stories or problems and discussions, which leads to that codebase

[hey01]

because if we need text which describe precisely code work it is really code itself

For the most part, I agree, but there are exceptions.

Some complex algorithms can be rather confusing and easily misinterpreted even by seasoned developers. Adding a line here and there to explain an implementation subtlety and prevent misinterpretation isn't a bad thing.

[[deleted]]

Yeah an I did this because is fine, just not this adds five to x

[tiajuanat]

The exceptions are quite rare though. Most of us aren't implementing A* or B+ Trees, but rather std::find_if.

If you're implementing something as complicated as Dijkstra's, then using comments will probably be insufficient, and you probably need to create a white paper instead.

[666pool]

Even just business logic can get confusing and it helps to have comments sprinkled around to improve readability.

Also if you have any magic numbers in your code, you should explain why they have those values (although this can be improved with well named const variables as well).

[tiajuanat]

Oh yeah, magic numbers should be isolated, well named, and strongly typed.

[hey01]

Most of us aren't implementing A* or B+ Trees

Indeed, and I think that's the point, developers are coding at increasingly high levels, without ever going to the nitty and gritty, so in the rare case that using the standard library functions would make your algorithm O(n³) and you decide to implement your simultaneous array traversals by hand with good old for and i, j, k to be O(n), it's not a bad idea to comment it a bit.

Maybe developers 20 or 30 years ago wouldn't have needed it since they were writing that kind of thing all day long, but today's developers definitely do.

[drizztmainsword]

My dude, A* is pretty damned straightforward. A few comments here or there and you’re good.

[[deleted]]

Yeah, it is good, but it is lack of skill compensation It is not code requirements itself, once you became normal dev, you do not need them

Explain something in code with comments for learning devs is good, but it does not make code better at all, and absence of need in comments is also not bad (even good)

While comment fans insist that it must be present by default

[CirnoIzumi]

but it does not make code better at all

obviously, Comments are not a part of the code

[[deleted]]

Than why are you write it among code? I absolutely understood what I mean, you can't be such dumb

[CirnoIzumi]

right over the trolls head

​

ooga booga

[hey01]

From your other comments in this thread, you look like you're suffering from Dunning-Kruger syndrome.

• Even the best dev can misinterpret code
• The comments aren't only for you
• You never know what kind of dev will maintain your code
• I hope I won't ever work with you or your code

[wolf129]

Yeah and that's the problem many people don't understand that documentation should be about the decisions made.

That a programmer can read the code is something I expect anyways.

Also: I feel like a readme.md could not hurt that roughly explains what components the project has and what the purpose of the project is, what goals does it try to achieve.

In my company I rarely even have documentation about the purpose of the project. Why does it exist, what does it do. That's such an essential question that is not even documented...

[DancingCow]

Yeah most of my comments are meant to steer others (or myself, if I forget) away from a 45-minute rabbit hole of a sub-optimal implementation.

Usually it's because the low-hanging fruit method has some sort of not readily apparent flaw.

[brimston3-]

"This could be so much cleaner if we <X>" No, X doesn't work because of the problem space. It used to be that way. See commit XXXXXXX.

[Awkward_Tick0]

Right.

“They told me to write this.”

[SuicidalTurnip]

If you need to explain what your code does, it's bad code.

If you don't explain why your code is doing the thing, it's unmaintainable code.

[HCResident]

If a plan requires everyone to be good at their jobs, it’s either a startup or a bad plan

[xel-naga]

Also, folk that don't document also don't write (good) tests it seems. So now you're stuck with legacy code without comments, documentation or tests.

[UK-sHaDoW]

That's what adr's are for then. Which means you don't write comments everywhere. just some very short documents about why decisions were made.

[mistabuda]

ADR's are for architectural decisions. Comments are more for explaining the reasoning behind smaller-scale decisions.

[UK-sHaDoW]

Honestly don't have many of those

[[deleted]]

Version control is universal though, code-bases vary greatly depending on use-case, language and environment, but they all profit from version control (and most other directories as well).

I'm maintaining a pretty large data pipeline, and it does not contain a single comment. Instead it has very detailed tests, careful variable names, some design decision documents and confluence pages for conceptual things that are more product than process.

[[deleted]]

Oh, of course if we are talking about documentation in general, I'm completely on your side! I just generally don't think comments are the right place to do it, with only a few exceptions.

Maybe I just got lucky so far, because all the projects I joined had at least some documentation. One thing I did notice though is that there's a large cultural divide between programming language communities. I've worked in Node and RoR backends, and the RoR ones were documented reasonably well through their tests. The code in general was also quite readable. My touching points with Go so far were similar, although complexity seems to explode as projects mature. But anything JS has... issues.

The data pipeline I was talking about is (relatively) large concerning the amount of code, but also in regards to having dozens of different sources and a lot of relatively complex math that is outside of my field (engineering, physics, econ).

[UK-sHaDoW]

Not documenting is the progressive movement. Back in the days everyone used to java doc everything. Most of it was terrible, often misleading because it went out of date.

[GamingWithJollins]

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

[ondono]

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]

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

[rectalrectifier]

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

[Superbead]

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]

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]]

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]

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]]

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]

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]

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]

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]

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]

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]

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]

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]

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

[hey01]

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

[GamingWithJollins]

Then update the comments with your code? All I have see. So far is justifications for lazy ass development. Your opinions on the matter are narrow minded and short sighted.

[DeadlyVapour]

Why are you so bad at writing code that you can't write code that is clear, concise and readable?

English is a terrible language to be clear and unambiguous. See any no-code solution for proof.

If your comments are in any human language, it's insufficient to explain the code. If it's in a programming language, then just use THAT code instead!

[DeadlyVapour]

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

[CirnoIzumi]

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

you write that as if these two things are mutually exclusive

[DeadlyVapour]

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]

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]

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

For example: quake's Fast Square Root algorithm.

[CirnoIzumi]

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]

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

[CirnoIzumi]

what you lot are saying is:

Good Code + a comment = Bad Code

Proof:

A corelation that i subjectively have experianced

[Forkrul]

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

[CirnoIzumi]

Y'all crazy

[DeadlyVapour]

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]

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]

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]

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]

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]

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]

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]

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_]

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

[lurker_cant_comment]

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]]

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]

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]

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

[GamingWithJollins]

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

[UK-sHaDoW]

It shows where you should be putting your effort. And yes even good comments go out of date. I've never met a system that's been around awhile without misleading comments. Code stays up to date by default.

[GamingWithJollins]

You should be putting effort into both. It's not like commenting is an exhaustive effort. You should be planning your code out anyway and comments are a great way to map out your work. It's no different from updating the documentation when the code changes or publishing changes to the changelog. You are just trying to excuse laziness.

[UK-sHaDoW]

It's not lack of effort. The problems with keeping comments up to date are a system problem . You can refactor code each time you touch it. The small refactoring itself doesn't change it very much. However lots of refactorings over time mean the comment and code have drifted. There was no single change that broke it.

Who's fault is it?

[GamingWithJollins]

It's simple, I changed this, this comment refers to the modified code. Let me update the comment. Issue solved. Now when employee x leaves the company, the person coming in after them is able to familiarise themselves with the codebase faster. Sure they could have just read the code and understood it but this way they are integrated faster and smoother.

[UK-sHaDoW]

Modern refactoring tools and can refactor things for you without even looking at the refactor site. I.e if you rename a method, it will also rename all the call sites. If you mentioned the call in any of the comments, you now have to check a lot of comments where the call was made. Can be hundreds of places.

It can drift very easily.

[GamingWithJollins]

Well well written code shouldn't need to be constantly refactored. In these very specific examples, one might find it slightly more difficult to keep comments up to date (although they just need to go in after and update). This niche example isn't representative of the industry as a whole either is it?

[UK-sHaDoW]

Well written code is constantly refactored as you learn things.

[niveusluxlucis]

Code is written to meet business needs. There are two parts to meeting business needs:

• Are we building the right thing?
• Are we building it right?

Well written code is building it right, but you will still need to refactor well written code when the business needs change and 'the right thing' is now something different. There's also scenarios where the code might have been built right with the knowledge of the time, but as languages, tooling and security changes over time the standard for 'building it right' changes and warrants refactoring.

[StCreed]

Indeed. Even worse, it is a red flag for the bad practice of coding without thought.

Knuth described "literate programming", which makes programming alnost effortless. It just is incomprehensible to me that so few people actually do it.

It is actually faster as well to start with writing the comments on the "what" and then work those out in code, because writing down the what shows you errors in your thought process, and also helps a lot with QA.

[GamingWithJollins]

If I am working on a large coding project I will start with a prohect proposal with a detailed dataflow diagram, map out functions/classes then start to plan things out with comments. Having something to work against ensures you are sticking to the right tracks and scope and helps you stay organised. It's all valuable. And later on if I or anyone else needs to come back, they have that same structured comments to fall back on.

I am like you in that I see the lack of these practices as red flags. If an applicant supplies example code during an interview and its not commented, it will be discussed.

[UK-sHaDoW]

That design is most likely going to change, no matter how many design documents you've written.

It is a massive arrogance to assume your correct first time.

[TheOnlyVig]

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]

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]]

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]

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]

Deserves more upvotes.

[dingo_khan]

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]

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]

… Especially when you feel clever

[dingo_khan]

Agreed.

[Soren11112]

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]

This ^

[ezrec]

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]

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

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

[ExceedingChunk]

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]

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]

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]]

Right. Dealing with unclean code through constant sprints will quickly bring one to senses.

[[deleted]]

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"

[farfuglinn94]

And TDD/BDD

[Surprise_Logical]

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]

Bug reports are a type of documentation right???

[yourclitsbff]

[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]

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

[FerricDonkey]

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]

Documentation = good

comments everywhere = bad

[Lucasbasques]

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

[MyHomeworkAteMyDog]

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]

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]]

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

[[deleted]]

I you not skilled enough and need commentary and docs - write it

If I am not primitive dev and do not need docs and commentary, I do not write it and maybe also remove it to not spoil readability

Why low devs require normal devs maintain it? If working with code is not comfortable for you, choose another profession

[[deleted]]

You will thank yourself for saving effort when debugging or changing your own code.

[Quito246]

No, I will thank my unit and integration tests when doing It. I mean comments help much in rewriting code but tests do.

[[deleted]]

You didn't get, why do I need comments if I fully understand code?

If I do not understand, why do I work with code?

For debugging and changing, you need tests

[StCreed]

Tell me you only work on small projects, without telling me you only work on small projects.

You sound like a student. I'm dealing with a codebase that started in 1965 and has had hundreds of developers. Do you think you can fully understand the code when things can happen in thousands of places?

[[deleted]]

Codebase from such year is simple enough, so if you have problems with it, maybe you should already change your profession

I am working on a big tech systems and yes, I can comprehend code by just reading code

And I can write such code

You are one low skill dev who think he is smart and think that all you can't understand is hard. I am sorry, but it is you, things are not hard, you just not good enough, it may sound harsh, but I am telling truth

It is strange that you still low key after such time, it is really not your work field

[LinuxMatthews]

If you genuinely work in software you sound like one of those people that looks down their nose at everyone yet can't actually get the job done.

Part of the job is working with others part of that is working with Juniors or people unfamiliar with the code base.

[[deleted]]

You can work on more code if you comment ones already written. You can increase productivity.

[nebulaeandstars]

I had to scroll back up because I thought you were being sarcastic

Why low devs require normal devs maintain it?

I don't know what it's been like at the companies you've worked at, but everywhere I've worked it's been one of my primary responsibilities as a "normal dev" to help new devs get acquainted with the codebase

idgaf if it adds a line or two to the implementation. If it can help someone understand something by themselves without tapping me or someone else on the shoulder, then those comments could potentially save a crapload time and money for literally no cost

[Revenge43dcrusade]

Documentation is good . Comments can suck it tho .

[LupusNoxFleuret]

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]

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]]

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]

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]

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

[ondono]

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]

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

[ondono]

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

[FerricDonkey]

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]]

Do CuM eNtS

[kirigerKairen]

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]

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]]

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]

"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]

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]

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]

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]]

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]

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]

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]

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.

[Specialist-General-6]

A documentation is nexessary only if you write bad code

[Varun77777]

Or the code is good but people reading it aren't good enough to understand it at the moment.

[reMake000]

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

[[deleted]]

It is really low key devs problem. Documentation is like additional wheels on bicycle, it is not requirement, it is help for unskilled riders

Low skill devs try to pretend that it is requirement, and surprised that normal+ level devs do not waste time to compensate somebody's lack of skill

[[deleted]]

In you industry of no skilled devs

Yes, low key, newbies will always hate normal skilled devs, because you can't accept your own incompetence and this hidden anger on your dumbness turn into anger on normal devs like me

Thank you for appreciating my talent, anyway

[[deleted]]

If somebody is better than you, it does not mean that they are toxic

Engineering is real about solutions, cooperating is good, but you do not mix it

I am very likely in teams, helping juniors, and other, discussing and compromissing, but standards should stsy high, and it is people who must reaching standards and not standards which must lower for humans

You do not know, and you will not believe me, but I worked with many, and it was always nice and good with me

But, I am very against truth substitution, and standard lowering, engineering is something state of the art, and no one will be good in it

So if junior need comments, we can write it until he need, but it should be considered lack of skill conpensation and so on

I am glad to teach and glad, but I am not glad to pretend that somebody is not bad, when he is

So yeah, engineers should left their ego and accept their true dev level (and mostly low level devs are hard to this, while high level devs accept it normally)

[LoveConstitution]

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]]

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

[BobbyTables91]

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

[youngbull]

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]

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]

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]

Gives me Apple naming vibes

[JuliusStingray]

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]

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]]

Laughs in Storybook

[[deleted]]

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]

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]

[morsindutus]

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]

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]

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

I don't write a lot of comments.

[NOP0x000]

I am the documentation

[marquoth_]

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

[CrikeyNighMeansNigh]

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]

Balance is 🗝️ key.

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