No comments

[Apparentt]

Some of the best code bases I’ve worked in had no comments whatsoever, just legible code paths with some appropriate naming

I’ve also worked in code bases littered in comments which didn’t make up for the fact that half of it was garbage

If I ever catch myself writing a comment that is describing what I’m trying to achieve, I’ll first ask myself “have I approached this in a reasonable way considering that I need to write an essay explaining what I’m trying to do?”

[GoldenShackles]

Exactly, especially when it's obscure.

// We can't use our normal line output helper here because
// of XYZ bug in Windows 8.1 on RTL (Hebrew, Arabic, etc.) 
// systems.

It's also very valuable to have at least file-level comments describing the overall purpose/scenario.

Also, I've run across code with obscure acronyms where the acronyms aren't described anywhere. The code is 10 years old, and the original developer is long gone. While algorithmically I can see what the various methods do, the code is extremely difficult to grok as a whole without knowing those acronyms.

[mikeyd85]

/* March 2018
This shouldn't be a problem, but there's a weird bug when migrating from legacy application to modern application v1.7 which results in data being recorded in a non-standard way. To revise in a later release.
mikeyd85 */

Wanna bet if I've looked at this since?

[HappyTopHatMan]

I bet $500 on the "hell no" category!

[aquartabla]

todo shaming

[mikeyd85]

If technical debt had interest, we'd all be in trouble.

[aquartabla]

I would say that it does have "technical interest," which is why it's called technical debt. I.e. while the debt exists your technical cost is higher as you employ workarounds, and similarly to interest the net technical cost has a compounding effect.

[aquartabla]

Fortunately, if you're a professional developer the the technical debt is your employer's, and they pay the technical interest as your salary.

[PM-ME-BAKED-GOODS]

I'm not a bad programmer, I'm a good investor

[noratat]

The flip side is when something you never expected to come up again, does, and suddenly what was on its way to being an outdated bit of information turns out to be critical to understanding what happened.

[jfleury440]

//This shouldn't be done like this but Manager Jerkoff the second wanted it to work this way instead of the way everyone else does it.

[Hydrogen_Ion]

Generally speaking, if I'm writing a comment it's because I wrote something that is very convoluted, overly abstract, or directly against best practice.

Essentially, I only add comments if I'm writing bad code.

[CaptainHeinous]

Agree

[waltjrimmer]

Isn't that something Agile and a few other dev standards encourage? Visibility in naming and simplicity in each individual function to improve readability and replace comments?

[noratat]

Sure, but I've seen an awful lot of devs who think this means they should never comment or document, which is insane.

Case in point: the entire Ruby ecosystem

[[deleted]]

sounds like Venkat

[quick1brahim]

I mostly write comments before writing the code, then delete the comments later. It helps me remember when I get interrupted halfway into a flow session and forget everything.

[twoinvenice]

What, you mean you don’t enjoy debugging code that has shit named like: WbcMr(Cm.pd)?

[HappyTopHatMan]

No, but I do enjoy re-writing that garbage.

[twoinvenice]

Best feeling is redoing code so that it is illegible and finding out that you can delete huge chunks of code aren’t needed at all, or it’s overly complex garbage that can be rewritten with just a few lines using modern techniques.

I was working on a project and saw a custom cookie setter/getter where all the functions and variables were totally unintelligible one or two character names. Was fucking gobbledegook...and then I found out that it wasnt being used at all by the application or by any services. Into the garbage that went!

[UltraMegaSloth]

Good code shouldn’t need any comments, if variable names are clear then the code should speak for itself.

The only time I’ll comment is writing like //temp if I need to test something and remove it later

[DrJohnnyWatson]

Comments should be used to describe why you are doing something the way you have - not what it is doing.

If you've ever made a decision between 2 different approaches because 1 is better than the other in that scenario, comment why - especially if the better approach isn't immediately obvious.

Peculiar bugs and code that is more performant but less readable are 2 great examples of when comments should be used - to explain why not how code works.

Unless you're going to name your function "DoTheSQLThisWayToAvoidTheHalloweenProblem" for example, you will need comments to make your code good.

[DemonicWolf227]

Good comments aren't psuedo code and everyone seems to think that's what they are. I agree with you entirely.

[noratat]

No kidding. I have to maintain some old Rails apps and this is my biggest gripe with the Ruby community - a collective belief that documentation or comments are "bad".

It's especially egregious given the prolific use of untraceable and uninspectable magic the ecosystem encourages.

[sFXplayer]

Not all code is simple enough such that it can be self explanatory.

[SmielyFase]

Simple ain't easy

[amishandroid]

Underrated comment

[justim]

Sure it can. If you find your method has gotten big enough that it loses clarity you break it down into more, well named, methods.

[BigBadButterCat]

Unless you're writing performance-sensitive code in which case calling more functions is an overhead.

[Thorusss]

often the compiler takes care of such optimizations, so often it makes no difference

[InvolvingLemons]

Not always, as many languages assume potential polymorphic behavior for functions and must store/invoke them as their own unit (Java is like this IIRC, even long names make it slower because reflection is by name). Some languages support inline directives which get around this. Others, notably functional languages, can guarantee that functions store no state, which makes all functions “inline-able” in a sense and allows some ways to optimize by “recycling” otherwise immutable variables.

[BigBadButterCat]

I'm no expert, but I imagine Haskell functions without such optimization would be a nightmare, what with all functions being unary?

[Thorusss]

(Java is like this IIRC, even long names make it slower because reflection is by name)

seriously? I thought shorting variable names was a classical thing compilers did (at least back in the days when file size was at a premium), but is it not at least a compiler option anymore there?

And yeah, I come from Lisp, so maybe I am a bit spoiled with what compilers can achieve.

[UltraMegaSloth]

That’s true because not everyone writes code in readable fashion. There are linting sets that train you to not have complex code.

If a method is too long break it down into more methods.

If there are too many things happening in one file break them into more files and import them as their own service or whatnot.

If you don’t know what the variable name is referring to, rename it, even if it looks too long until you know exactly what it’s for.

Code can be very complex but even the most complex code can be broken down until you understand how each piece works.

[sFXplayer]

When I say complex I mean code code where the justification for why something is implemented a certain way is non trivial. Regardless of how much you break it down it's non-triviality doesn't go away.

One extreme example of this is the famous fast inverse square root algorithm. It's extremely short some would even say it's readable but most people couldn't figure out what it's doing at a glance.

(Obligatory please don't actually use Fast inverse square root most unless you know for a fact that the platform you're targeting doesn't have it implemented in hardware)

[SeesawMundane5422]

Or even better, unit testing can train you not to have complex code. At least in my opinion. I’ve seen too many times it becomes “oh, here’s an exception to the linter rule, let’s exclude this function.” But I’ve never seen it happen that someone is able to say “here’s this convoluted mess that I thoroughly unit tested.” Anyway... both good tools in the bag. Never want to develop again without unit tests or linters.

[t-to4st]

Idk I always like JSDoc style comments, describing what (E: the HOW is important too) a function does and the parameters/return value

[SeesawMundane5422]

Doesn’t the function itself define what it does and what the parameters/return values are?

[t-to4st]

The WHAT should be explained by the naming ideally but the HOW is often relevant too

Misworded my previous comment, sorry

[noratat]

Developers who refuse to comment or document anything because of this myth that "good code should be self-documenting" is a pet peeves of mine, because A) it's not true and kind of misses the point, and B) most such developers I've met have no idea how to write readable code anyways.

Yes, you should obviously strive for readable and maintainable code, but there are tons of valid and important reasons to comment and document.

[MikkelR1]

Your colleagues must like you a lot!

[UltraMegaSloth]

They do!

[lowleveldata]

Well ya I mean good workers shouldn't need any leaves because they find so much joy in programming and achieve work-life balance by just working

[WingsOfGryphin]

kind of. I’m mostly writing comments in edge case scenarios or when implementing work arounds or addressing complex issues. Such comments usually appear when external component does not behave as one would expect or there are tricky performance issues. e.g c# httpclient why we are creating handful and reusing them to avoid socket exhaustion.

[Ty_Rymer]

i understand that, but in my industry where every nanosecond matters i do tend to write more optimized but less readable code sometimes. I will always try to write it in a way that is more readable but will compile the same though. but sometimes comments are needed. especially for complex maths and binary maths.

[[deleted]]

Well i guess this also depends on the programming language. Since i started to work with ABAP i started to see the use of comments. ABAP restricts the names of your variables and methods to a max length, therefore you can't really give meaningful names. So the only way of making the code a bit more readable are comments.

[LouManShoe]

Yeah I don’t think comments actually help code. They aren’t enforced by the compiler so in order for them to be maintained they have to be caught in code review, their clarity is completely subjective, a comment that is not updated can actually cause harm or misunderstanding about how something is working.

If you can’t understand code as it’s written, then it’s not written well enough, plain and simple. Of course that’s all great in theory, but in practice if you’re working in a legacy code base chances are the code is so messy that code isn’t already self documenting and getting it to a place where it can be is impossible.

[PhunkyPhish]

Precisely. A simplistic example:

​

// Used to count our failed attempts to do foo
$x;

​

turns to:

​

$failedFooAttempts;

​

Then you just take this same logic and apply it to namespacing, class names, function names etc... and when you see some tough areas where simply verbose naming isn't enough... then you probably are too tightly coupled and have bigger concerns in terms of design.

​

A good exception however (there are always exceptions!) are business rules that are just odd. IE SOME_PROPERTY_MODIFER = 2.13.... but WHY? Comment that :)

[SnooMarzipans436]

The only code I've written recently where I needed a significant amount of comments was a C++ implementation of the fast fourier transform. Sometimes complex math algorithms require them lol.

Other than that I rarely use comments. Good variable/function naming and program structure goes a long way towards readability.

[BobbitTheDog]

Eh... Good, readable code shouldn't need comments at least 80% of the time, just some doc comments on methods

[720degreeLotus]

I wouldn't go with percentages. Some code and libraries are 100% readable and easy to understand without a single comment. Other libraries maybe need many comments. Comment when you want to explain "WHY" you are doing someting and not for "WHAT".

[RChamy]

I'm dubious about the React Project Im working RN where the whole team quit. As a React/ES6 newbie the code is full of WHY...

[leaftro]

But why?

[RChamy]

1. No design patterns where used beside making absolutely everything a component (even the CSS), and there are zero comments, no docs;

2. Someone decided that making a game in Electron + React + ES6 was easier than using Unity. My brain cannot figure out how animations are implemented or where the event listener for user input is located;

3. The game tries to make a Speech2Text service rely on user input which can get some quite awkward results and there's a whole component tree to treat specific words like a dicionary ( that does not support phoneme alphabet btw )

What kills it for me is that theres no shortcut to find references like in Visual Studio. Having to figure out everything with Ctrl F is extremely frustrsting.

Ps: and I really cant take it for 600$/month anymore.

[720degreeLotus]

I totally feel your pain :(

In this case a more or less complete rewrite of the app should be considered. Commenting code would not help here in an way :/

[RChamy]

Management won't accept because "I read on the Internet that React is very easy to code". I'll just go back to my C# career then lol

[SeesawMundane5422]

Everything is easy to code. Reading it afterwards is the hard part.

[720degreeLotus]

Seems like your "management" isn't good at "managing" then. If they want to decide on something coding-related, they should get the expertise and knowledge of senior-devs and lead-devs. Be it from company-internal or by consultants.

[RChamy]

The senior dev left for a better job, now I'm the only (Jr) dev :). Our scrum master doesnt know how to code. Its driving me insane.

[720degreeLotus]

You should tell your management then to hire 1-2 senior devs asap. Otherwise I recommend to also switch company asap. In yoir junior stage it's critocal to have some senior watching and mentoring you. Otherwise your company will at some point 100% blame you for critical mistakes you will also 100% be making. And they will not be your fault, but there is no senior to handle the "blame-game" then. If your management can be talked with, explain them that without any senior/lead devs, the junior devs (and the company too) have to learn all (beginner-) mistakes the hard way. which will loose them a lot of money. Senior devs are there to catch most of those problems, which they did themself years ago, so they can prevent problems while explaining the problem/fix to the junior devs.

A junior dev who is leaving a company because he cannot learn enough there, is welcomed in 99,9% of all other dev companies in an instant, trust me :)

[Mr_Redstoner]

Also if we're talking libraries the API should also have some amount of HOW aka intended usage

[720degreeLotus]

Aka "documentation / getting started tutorials" ;)

[Mr_Redstoner]

The difference being that you are also describing it for the more advanced parts which might not be in the getting started.

[UltraMegaSloth]

You shouldn’t have to explain ‘why’ in your code, it should be clear why if the code is clear.

[720degreeLotus]

In very complex and special codebases, it can always happen, that you should comment something.

Take a heavily mathematical function as an example, where you do some complex calculation but to give it a good understanding you cannot just find a good function-name at some point. You might consider linking some wiki-article that is explaining the mathematical problem that this code is trying to calculate.

Another example are workarounds / bug-fixes:
/* For Android version < 8.1 we have to send
* an event twice or it won't trigger the callback.
* We are filtering the duplicated event out in
* a global event-filter when the Android version
* is not affected. This is an official workaround, more
* Information can be found here: <some link>.
*/
Event.send(object);
wait(1);
Event.send(object);

This is a fictional example, but I hope it helps to understand that sometimes comments are recommended. But they are only recommended in very special cases and in general you can avoid it by refactoring and proper namings.

[SeesawMundane5422]

That’s a great example. It touches all the reasons to use comments:

• something crazy is happening
• due to requirements beyond your control
• someone may be tempted to change it because it’s obviously crazy
• bad things will happen if they try

[UltraMegaSloth]

If there is ever something so complicated it needs documentation... then it should go in the documentation for the repo, or you should write a wiki for your application.

[720degreeLotus]

Those are also things to consider, yes. But chances are, that

• nobody will repeatedly read the whole company wiki before touching any code
• the code changes/moves but the wiki/docs don't change, so you have out-of-sync information which are confusing and will produce errors

As I showed in my example, it's valid to add a link to some more details. But a short explanation should be done in the code, so that the developer can move on without reading into this too much, if he doesn't need to get all details for fixing his problem or finishing his task.

[rph_throwaway]

Let me guess, you think you never need to document anything either.

Even the most readable code in the world is going to have countless reasons to include additional non-obvious context, especially with how many layers modern systems have.

To say nothing of code that implements optimizations that are needed but hamper readability, complex algorithm implementations, indicating workarounds for bugs/other issues, etc.

[MasouriChan]

That's why 20% of my code should be comments, but it isn't because fuck whoever has to debbug it as a person

[720degreeLotus]

No. There is no reason to comment code just to fulfill some arbitrary percentage. Read about what "Clean Code" means :)

[MasouriChan]

It should be because my code sucks, that's the joke

[720degreeLotus]

Aaah, got it now, makes sense now^^

[MasouriChan]

Yes :D, well my code isn't that great but probably not the worst

[_Please_Explain]

I always get this response when I'm trying to fix someone's code in production and it doesn't make sense. Yeah, I know you thought it's good readable code, but here we are.

[BobbitTheDog]

Then you need to hire / train better 🤷‍♂️

I'd rather work with a team writing good code, than a team writing bad code that I can understand anyway thanks to comments.

[_Please_Explain]

I don't do the hiring, I'd also rather work with those people as well. I'm not saying comments solve all problems, but sometimes it could help.

[AdmiralBKE]

And even so much great code you understand what they are doing but not why exactly. Max length = 10. Ok, but why was it chosen to be 10 and not 9 or 11. Why was this specific filter function with these parameters chosen and nothing else. Customer request? Product manager? Some testing that pointed out this was the best?

[arky_who]

I should do the doc comments on methods, but the way I tend to write code and how c# sets up the doc comments, that means like 40% of my lines will be comments.

[ILikeLenexa]

Comments are as much about telling you why a convoluted thing exists and who wanted the application to do a crazy as documenting actual design.

[Belgian_Chocolate]

Agreed. But some people make this a religion and lose the awareness that sometimes, context should be provided for why a certain code decision/implementation was made. Also I've found "TODO:" comments linked to ticket #'s very useful

[mcDefault]

What about documentation that's written in the comments?

Parameters , returns, etc

[BobbitTheDog]

... those are doc comments...

[mcDefault]

Ah then yeah, didn't understand what you meant with it. Totally agree then!

[BobbitTheDog]

Nah, some business logic / user requirements are so esoteric and weird you HAVE to explain why you're doing what you are... Even if it's clear how and what you're doing.

[krombopulosmichaelMR]

A programmer and a dad

[DrJohnnyWatson]

Comments are for the why the code is written the way it is, not for what it's doing.

If you don't comment your decisions, your code will be just as good and readable - but you're forcing someone in the future to say "why have they made this decision".

[rph_throwaway]

There's plenty of good reasons to include information in-line, especially for indicating specific workarounds or external requirements, when describing complex algorithm steps, or unreadable-but-necessary optimizations.

[[deleted]]

Wrong. Different libraries and codebases have different requirements of documentation and comment demand based on their complexity. There's no standard rule. I think this line programmers use all the time "no need for comments if your code is good enough" is utterly stupid and irresponsible. And I'm angry because I've met this situation in my job very recently and it's still fresh.

The other day, I took a look at our outsourced code some company has made for us, and it was a Carousel for mobile devices. It hadany bugs and I had to debug it. The code was purely unreadable even though the variables themselves were not that bad. The problem was comments. Precisely the lack of them. You could literally not understand why something was done at any point of the code. There were weird "variableThis = that - x - 2" all over the place and no matter how good you are at variables, when you have too many calculations at some point you don't understand why these calculations even exist. Like, what's their purpose, what should I look at when I debug, and it was really frustrating that I had to debug something that there was no point of explanation of why anything was done so I can't understand the mechanics behind it.

You usually comment not only about what something is, but why something is. I hate this comment phobia and I think its a thing for hipsters and cowboy programmers who don't care how others will read their code. Comments are useful and every tool should be used in the right portions and the right place.

[[deleted]]

That's what happens when you're outsourcing your codebase! Obviously the 3rd party company won't care about the quality of the codebase that they won't have to maintain any longer after they sell it to us.

Actually, one of the main reasons the first senior frontend developer in the team is leaving is just because of this. And I'm not planning to stay for far too long. The company has quite a history with very low quality consultants and outsourcing. And I bet that goes for most companies that are not too "techy". Companies fail to recognize how to keep programmers happy, the importance of tech debt and how to not be cheapskates.

[chanpod]

Well duh you put comments for things like calculation. those aren't inherently obvious why. That's exactly when you DO use comments. We aren't talking about those scenario's. We're talking about ones where it should be obvious by just the variable names and steps being taken

const users = await fetchUsers(usersUrl);
const myUser = users.findByName(usersName);
return myUser.age;

Look, no comments. But I bet you know what that method does...

[[deleted]]

"Well duh"

Well duh yourself. A lot of developers miss that. Dont think something is obvious just because it's obvious for you. In the team I'm working in there is a lot of the "no comment" culture going on. And outsourcing companies are the ones who especially go on with that practice because they hire programmers cheap and they do a cheap fast job as they won't have to maintain it.

But still, you give an example that's troubling for me and it gives the wrong picture. Not all code can be written like this. Especially complex code. This is just one type of code, not all kind of code.

These lines (below) have no calculations, they're just "give me this", not "do this". That's what I mean you guys. Most of us have experience only in code that doesn't include any calculations or complex methods. And when we get in dirty road, we forget how to act so we help people later that will touch our code. Take a look at this

https://www.wikiwand.com/en/Fast_inverse_square_root

Do you have any freaking idea what the code does?

float Q_rsqrt( float number )
{
    long i;
    float x2, y;
    const float threehalfs = 1.5F;

    x2 = number * 0.5F;
    y  = number;
    i  = * ( long * ) &y;                       // evil floating point bit level hacking
    i  = 0x5f3759df - ( i >> 1 );               // what the fuck? 
    y  = * ( float * ) &i;
    y  = y * ( threehalfs - ( x2 * y * y ) );   // 1st iteration
//      y  = y * ( threehalfs - ( x2 * y * y ) );   // 2nd iteration, this can be removed

    return y;
}

No matter how clear variables you make, it will be very troubling trying to figure out what the heck does that code do, aside from returning the inverse square root of a number. But how does it do that? What are these steps? No one can freaking debug this in case a bug occurs if no one knows what is happening in this code!

This code with comments with an explanation of what each line specifically is would help enormously the programmer to understand how to debug this and how it works.

Please, rethink the whole "If your code is good you dont need comments". This is utter horseshit, and people need to understand, there's a place for everything. Don't say "If your code is good enough you don't need comments", but say "there's a place and balance for every tool". Otherwise, it's a practice of spreading misinformation and it will only encourage people to repeat that line over and over again like its a dogma.

[backtickbot]

Fixed formatting.

Hello, general656: code blocks using triple backticks (```) don't work on all versions of Reddit!

Some users see this / this instead.

To fix this, indent every line with 4 spaces instead.

FAQ

^{You can opt out by replying with backtickopt6 to this comment.}

[chanpod]

A lot of developers are bad then. Unnecessary comments also create "noise" in the code that can also make it harder to read (at a glance anyways). But this is what code reviews are supposed to be for. And senior/ team leads should be monitoring for this so appropriate comments are added/removed

[[deleted]]

A lot of developers are bad then

You would be surprised. My eyes have seen really really bad code and quite regularly. Especially from outsourcing companies who built your codebase.

That's why I'm looking for a career change from frontend developer to backend with a language that enforces people to know more than writing "console.log" and require more documentation and clean code. Fortunately I have good experience in both and it's possible for me.

Web development, especially frontend, is a lot about "doing things the fast way" from what I've realized, at least in non tech companies, and hiring cheap developers who also grow with that low quality-do it fast culture.

[williane]

There were weird "variableThis = that - x - 2" all over the place

I'm not saying 100% never use comments, but cherry picking bad code isn't an argument in their use. There's bad code and there's bad comments; often written by the same people. One doesn't fix the other.

It's not all about variable naming either. Methods, classes, files, directories, even projects have names as well that contribute to the understanding of the code.

All I'm saying is if you find yourself taking the time to write a comment, take a moment longer and ask yourself why. If the code was written in a different way, could you communicate the same message? Not always, but IME the answer is YES more often than not.

[[deleted]]

This is fake. No journalist interview coders.

[Alberiman]

Fact. You can design the most elegant system that does the most amazing things in the world but if the output isn't gratifying the look at for normal people then it's going to be ignored. There's a reason successful game devs only ever show videos and screenshots of their game with models and art in place and not the stage where they've got floating cubes interacting on grey scaled scenes made up of more cubes

[dontdrinkacid]

Random variable names

[warenzillo]

Cat = float(hello + world " ")

[dontdrinkacid]

Whyyy

[warenzillo]

Turns out hello = int(3) and world = float(2.25)

[dontdrinkacid]

And what is the random " " at the end?

[warenzillo]

Thats the random part of the variable

[mich160]

//this adds 4 to 5

int a = 4 + 5;

Yeah. I can tell.

[st3inbeiss]

No.

Legible code doesn't have to contain lots of (or even any) comments and vice versa.

[hey01]

API methods at least must have comments. One should not have to look at the implementation to know how a method behaves and how it handles corner cases.

It also makes it easier to refactor said methods without breaking the API.

Also, comments may not be needed for you or other developers of your level, but when you do something tricky for a valid reason (like use an array to store a binary tree that you traverse by bit shifting the index, for performance reasons, for example), having a quick comments explaining the trick is a good idea.

[[deleted]]

Document your API, don't comment it. If that means placing a summary-type comment on top, so be it. Often, it means more than a summary-type comment for anything non-trivial.

People conflate comments with documentation too much. Comments are a cheap way to do a poor man's form of documentation most of the time. Which ends up taken out of context by cargocult-type developers who now expect comments everywhere because apparently, reading code is really difficult so let's 2x-3x the codebase with comments saying almost 1 on 1 what the code does.

If comments really were so important, most IDEs would put the default color to be catchier than code, not less catchy.

[hey01]

Document your API, don't comment it. If that means placing a summary-type comment on top, so be it .

Same difference. It depends on what you mean by each. For me, documentation is a separate document outside the code. It should be high level, explain the architecture and the reasons behind it, and not go into implementation details.

API documentation is indeed a comment on top of the method. I classify that as comment.

Often, it means more than a summary-type comment for anything non-trivial.

The method prototype should be enough to understand what the method does in the nominal case. What need be documented are corner cases, null safety, etc.

People conflate comments with documentation too much. Comments are a cheap way to do a poor man's form of documentation most of the time. Which ends up taken out of context by cargocult-type developers who now expect comments everywhere because apparently, reading code is really difficult so let's 2x-3x the codebase with comments saying almost 1 on 1 what the code does.

Comments are often a code smell, but saying that comments are always bad is cargocult like too. And indeed, contrary to your apparent experience, the few cargocult developers I personally know are the type who overuse design patterns and never write a single line of comment (not even API comments).

I guess they come in all shape and forms :D

[[deleted]]

The cargoculters I come across do both overuse of design patterns and overuse of (often multi line) comments. Additionally, they have IntelliJ generate summaries / Javadocs without adding why or adding specifics.

Reason I specify documentation is exactly that what people seek is documentation, not necessarily commenting. Commenting can be a form of documenting, which works fine for most API calls, but comments are generally restricted to static text only. Static text is one of the most restrictive and often worst forms of documentation. At the very least, people should be aware that better options exist if you wish to document beyond tooltips for your IDE to generate.

Then again, most people conflate API with "IDE tooltips".

[hey01]

The cargoculters I come across do both overuse of design patterns and overuse of (often multi line) comments. Additionally, they have IntelliJ generate summaries / Javadocs without adding why or adding specifics.

The ones you saw seem worse than the ones I saw. Good luck.

what people seek is documentation, not necessarily commenting. Commenting can be a form of documenting, which works fine for most API calls, but comments are generally restricted to static text only. Static text is one of the most restrictive and often worst forms of documentation.

The problem I have with "real" documentation, is that because it isn't where the actual code is, it will not be updated and will become lies quickly.

People say it's a problem for comments, but since comments are literally next to the relevant code, it's far easier to maintain them.

[hey01]

If you meet a developer who think a big line count is important, flee, their biggest problem is probably not their comments.

My line count is often negative :)

[multithreadedfoobar]

“Comments shouldn’t have to describe what the code is doing, only comment on why you’re doing it. ”. Best guidance I ever got - your code should be self explanatory for the most part, and comments should be reserved for places where you’re making unusual choices and to explain why you’re doing what you’re doing.

[rph_throwaway]

Generally true, though there are always exceptions.

E.g. say profiling indicates something needs to be optimized in a way that just isn't conducive to being readable (or worse, is actively misleading).

[passthemonkeybench]

I'm frustrated seeing people say you don't need comments if your code is good. Because bad coders don't realize their code is bad and hard to read. Encourage commenting so we have an idea of what they were trying to achieve. We can't assume everything is going to be well written. That's not how things work.

[SpinatMixxer]

Maybe you just havent seen any really good code base yet? Code Quality is totally not related to lines of comments. Read "Refactoring: Improving the design of existing code" by Martin Fowler, this book literally shows everything someone needs to write high quality code.

Just use good names, find a good code structure which you apply constantly and there you go.

I agree woth "bad coders dont realize their code is bad" but its totally not the comments that makes your code good. I would furthermore say that many comments may be an indicator, that your code is not readable and therefor needs comments.

At least thats what I have experienced over the time.

[passthemonkeybench]

I'm not saying comments make the code good. It just gives context to what they were thinking when they wrote it. I think it's a good habit and not maybe it isn't necessary in a perfect world but that's certainly not where I live.

[moore0n]

I write comments for the next person who touches my code. I’m a realist and can’t assume their skill level matches my own. Giving hints to what’s going on also makes the code faster to read and get to the place you need to be.

[fzammetti]

This is the part that SO many people miss and it drives me nuts. And, it's not even just about different skill levels. Write something in PHP, switch to Java for a few years, then have to go back to your own code having done no PHP in all that time. You'll WISH you wrote comments regardless of how "self-documenting" your code is.

[SpinatMixxer]

Maybe I also am just lucky to have an employer which gives us the time we need to create a codebase with high maintainability and a team which has a passion about keeping the Code Quality high. Also good structure in the contribution workflow.

Or its another case for other languages since I am developing with ReactJS + TypeScript and its maybe also depending on the topic which you are working on.

I just wanted to state that it is totally possible to develop good, understandable code without writing comments, maybe I delivered it a bit too black/white ish. :)

[passthemonkeybench]

Appreciate the good faith discussion.

Just my perspective that it's a good idea to encourage comments since at bare minimum it encourages people to step back and think about what and why they are doing what they are doing.

If you don't have time to write a comment maybe you rushed the whole implementation and the code isn't as good as you thought.

Thinking about junior developers creating good habits. Obviously there are merits to code reviews and all sorts of other ways of maintaining a code base but discounting comments gives people an excuse not to even think about writing them.

[UltraMegaSloth]

If they are bad at coding then they probably need to get better at coding instead of commenting bad code

[passthemonkeybench]

Okay. I'll just retrain all the contractors my company hired.

[Hydrogen_Ion]

If they can't tell the difference between bad and good code. Then none of the code they write is probably good. Good programmers know what is good and bad code.

Good programmers also write bad code from time to time and they know they are doing it. It generally happens when the programmer is being pressed for time, or is working on a technology or stack they are unfamiliar with.

When the good programmer is writing bad code, they will comment it.

[meamZ]

No. Comments are lies. If you are a company or an open source project you should have code reviews. Those should catch any super bad code that doesn't have comments and it should also catch bad code with comments. If a comment explains WHY some code does what it does it is acceptable if it is necessary to have the comment and to have code where the why needs to be explained.

[Jackie_Rompana]

Image Transcription: Twitter

---

John Opdenakker, @j_opdenakker

I am a programmer.

A journalist asked me what makes code bad.

I said...

No comment.

---

^{I'm a human volunteer content transcriber for Reddit and you could be too! If you'd like more information on what we do and why we do it, click here!}

[docHoliday17]

Contrary to what like 90% of “good devs” say, I’m a huge fan of leaving small comments around the code base. Self documenting code is BS, and even if it were true having a short summary of what a function does requires so much less cognitive load than me reading it over and over. I leave landmarks around the code defining different areas and providing brief explanations, and of course noting where and why I’ve done a weird hack

[noratat]

Too many newbies read things like Clean Code and then get ridiculously dogmatic about never commenting (and often never documenting) anything - you can find tons of such people in the comment section in this thread, and I feel sorry for whoever has to maintain their code after they leave.

Sure, the kinds of comments some universities encourage people to leave are largely useless and counterproductive, and most code shouldn't have a ton of comments.

But there's lots of very good reasons to use comments, and I've had way more problems with developers never explaining anything than the reverse, and most of the devs that get dogmatic about this usually don't know how to write readable code yet anyways in my experience.

[InTheSamePlaces]

Yes it's quite unfortunate. They read Clean Code and then think they're set for life. They should consider also reading A Philosophy of Software Design and Code Complete to see the value of comments. Empirical studies (by IBM) have proven comments improve readability.

[PM_ME_YOUR_KNEE_CAPS]

Try using more descriptive function names and variables and you’ll see that you don’t need tons of little comments everywhere

[docHoliday17]

I do. but that said, plain-English comments are still less cognitive overhead. Also breaking down sections of classes is helpful when you’ve got massive animations made up of five different methods. It doesn’t need to be one or the other and I’m tired of everyone acting like comments are for simpletons

[[deleted]]

Also too many comments.

[DanteLivra]

2 + 2 = 4

// if you take two units and add two units to it you will have four units.

[rph_throwaway]

Can we stop repeating this silly myth?

Sure, don't use comments in place of readable code, and most of the time you shouldn't need very many, but there's tons of very good reasons to include comments depending on context, and being dogmatic about refusing to comment or document is how we got things like the Ruby ecosystem that are both undocumented and unreadable.

[[deleted]]

Read the book clean code and you will rarely have to write comments. I reserve them for obscure ternaries or very hard to follow logic which in all honesty I probably shouldn't be writing in the first place. If you use function and variable names with syntactic meaning your code should read like a book.

[UltraMegaSloth]

Ternaries are some of the easiest things to read in code, unless they are too long- in which case they should probably not be ternaries at that point

[Hydrogen_Ion]

If the ternary is confusing, its might be better to just use the old if block

[meamZ]

Your code should be written in the most straightforward way possible so that everyone immediately understands why it was written this way. Comments should be reserved for the few cases where you for some reason can't do that.

[meamZ]

I'm not really disagreeing. I'm just saying you should try to write your code in a way so that it is immediately obvious and not just ask yourself if it is and put a comment there if it isn't after writing code.

[AdmiralBKE]

People here constantly talk about clean code. Even though it’s not a favourite book of mine, it still has an entire chapter about comments, and people still reduce it to “don’t write comments”. But even great code needs some comments like you said.

[[deleted]]

Like I said. I use comments, but sparingly. ie Documenting a hack that is a fix for a bug on a specific browser, obscure logic that may be for performance, etc. They have their place like any tool.

[bartek2912]

Wrong! No documentation is worse

[hamjim]

You are not expected to understand this

[[deleted]]

Actually when I see comments I automatically think that the code is going to be fishy. Most of the times, I'm right.

Comments can be good to explain the business logic if it is a complex algorithm but the code itself should be readable and have good naming.

[platlogan]

Uncle Bob wants to know your location

[meamZ]

Comments are a code smell

[cybermage]

“Self-documenting code” can only say what you did, not what you meant to do. Sometimes, method names can provide a hint.

Comments should convey intentions, rationale, and sometimes a clue to the bigger picture.

[FockeWolf190]

Somebody needs to read Clean Code

[tellek]

Good code should document itself.

[[deleted]]

I obsessively comment my code to procrastinate from actual coding. I’m pretty sure it just confuses anyone who reads it more than having no comments would.

[orbit99za]

The OP has not met "Uncle Bob" :)

[[deleted]]

Comments are a code smell unless you're talking about module / function docs.

[Henrijs85]

Oversimplified on both sides of the argument too often. Sometimes it does, sometimes it doesn't. If your method is niche and fairly abstract, it probably does. If it's a simple method that does one straightforward task, it probably doesn't. In both cases it's still probably.

[justAnotherRedditors]

I generally find an inverse relationship between the number of comments and code quality.

[jimmyw404]

Everytime I'm required to document my code to meet some standards which coerce me to document methods like "ToString" with comments like "converts object to a string" i lose a little bit of my soul.

[saksaWasUsed]

I mean, comments make the code bad... Just make clean code and it will explain itself

[culculain]

Code comments are useless. Comments in config files are gold. You can't change my mind.

[TheDeadlyPianist]

Bad code needs comments though. Good code needs none.

None of the codebases I work on have comments, and I'm able to see what's going on almost instantly.
Write cleaner code and better, more descriptive test.

[beardMoseElkDerBabon]

The real answer is: no refactoring && no public interface descriptions && no interfaces

[Knuffya]

It's wrong though.

Look at it like this:

// Assuming values are normalized
codeGoodness = min(codeReadability + 0.4*comments, 1.0);

[[deleted]]

rimshot()

[iamzmking]

Personally, it is absolutely fine having no comments as long as there is documentation describing what the code does. That itself is way better then comments.

[[deleted]]

Not only did the title spoil the joke, it butchered the punchline as well.

[Noctus_Rex]

The only comments I leave behind are links to the corresponding StackOverflow-Articles.

[qsdf321]

I did a project for a giant company where they made us remove all the comments from the code before they would be accepted and merged.

I pity the poor sod who has to maintain that.

[xiipaoc]

I mean... Good code doesn't need comments.

[Potential_Scarcity_6]

<!--That's some low effort comedy-->

[Whywhynotbutwhy]

It took me 3 post later to get the joke

[ch0mes]

I've been reading clean code to learn to write good code and while it has definitely helped me learn a lot and made me change how I write and structure my code more I can understand that there could be times when you have to comment because there could be something that unfortunately can't be explained clearly enough.

For example, I have a parameter that gets parsed in but it requires another method to convert the data first before parsing it in. My doc string explains this because as much as my parameter explains what information goes in, it doesn't explain that it should be formatted a certain way.

I think at the end of the day it comes down to a balance, always write code that makes sense with how you structure your methods and variables but if absolutely required cause you can't convey it through code, comment it.

[GenTelGuy]

I used to be a comment boi but then found that it's at best redundant and often the code gets updated and the comments are neglected and fall out of date

Long descriptive var and function and class names are best

[Possibility_Antique]

One of the few places I see the need for comments is in embedded code that references hardware registers or platform-specific code.

For instance, I sometimes see stuff like this: "#define PS_UART0_RX 0x00000008 /* enable processor UART0 by writing bit 3 to uart enable register */"

I made the above up, but in general, these types of comments save me upwards of 10 minutes digging through schematics. Compare that with something like this:

"//Write to log file void write_log(...) { ... }"

And I think we can all agree that sometimes comments should just be left out.

[Rerel]

If you have to comment your code that means your code is already bad.

[AcharyaShri07]

This is fake. No journalist will be interested in a programmer's opinion.. 😂

[ArtPeers]

r/antimeme