!rant
How many of you developers agree with Robert C Martin that commenting should be avoided as much as possible and that it should only arise when we fail to express ourself effectively through code.

You also have too keep in mind that most people learn from reading other people's code. By commenting, you help them better understand what's going on.

@g-m-f this isn't to say that all commenting is bad of course, to use commenting as clarity is one of the exceptions. For example when you are using a class from a library that happens to have some confusing elements to it you can write a comment to clarify and help others understand whatever was proving to be confusing...The class can't be modified so a comment is justifiable. Martin is emphasizing that you should strive to write everything with care and thought so the code narratives the logic clearly enough to not use comments. He even makes the argument that comments can be misleading and become less accurate with time as the code changes; a lot of the time would have to go towards maintaining the comments accuracy as the code changes, when you could've been working on making the code itself clearer and cleaner.@Cyanite

Depends on the use case.

If you are writing a library/sdk/API then comments should be there to show HOW to use it, not how it's implemented. Otherwise, I fairly agree.

@viking8 this is speaking on mainly a function/class level. Uml modeling can have comments anywhere it seems fit.

I have just completed a computing degree but every time I write comments in my code I feel like I'm insulting the readers intelligence so I don't write it. I never really thought of writing about why it's a method but I will from now on. I completely agree with the sdk/api argument.

That is so true. That can be very dangerous, especially for new programmers who rely on comments. They expect the code to reflect what the comment says but can't always be sure of that.

@dalastTomCruise back to my point above - if you are writing library code and the comments are supposed to give a description of usage and return values. In cases where Intellisense use comments for tool tips, those comments are part of the code and should exist. They should not describe how things are done, just what the function could provide. Failure to update the documentation should be detected in a code review.

Inside that function, comments could exist for clarification, but not description. Like "converting to km instead of mm to prevent precision loss", to describe that magic number there

@kaqqao this is from Robert C Martins Clean Code, not from "stupid flammable shit articles". Just to clarify, this advice is saying to GENERALLY avoid comments at function level by expressing the algorithm efficiently enough to require very few if any. Has nothing to do with expressing with code why you chose this implementation...

@dalastTomCruise disagree.

If 1 guy makes a function and i needed i shouldnt look through a the function to know what to give and what is returning.

A lot of IDE even show the comments before function so you know which parameter you need to send which are optional and whats returning.

In no way in any circumstances you should re-understand a function before you use it. As long as you know what it does(what you give/parameters and what is returning and is good for your case) then thats good code.

@viking8 Those kinds of comments are design oriented ones and are perfect. The code on design level changes very rarely if at all.

@curlyDev and I agree, it was a poor example. Functions are black boxes and nothing more. That's why I deleted my comment before you even responded. How did you even manage to read it? But you are using a nice ide to confirm the new return types, hypothetically what if the developer is using a plain text editor and doesn't have that convenience, but he does remember the comment and puts faith in it?

@dalastTomCruise the bad point I made earlier didn't really support the real point. Which is if you are commenting at function level you are most likely doing too many things in the function at different levels of abstraction to where it is a hassle to understand without comments. You can eliminate the need for the comment making sure that your function does one thing and one thing only. This is a general rule of thumb so don't take it as law. If your function does more than one thing than your naming of the function should express that clearly (addAndSubstractFromTotal)- in this method it is clear that we are adding and subtracting and those operations are in the same level if abstraction.

@curlyDev another point is that humans are not perfect and writing a lot of comments means you have to keep up with how accurate they are as the code changes which increases the odds of overlooking a comment that needs to be changed.

@curlyDev and fyi you are clearly defending a bad comment. Why comment the return type of a function in the first place when it's provided by the ide?

I feel like I write bad code because I do what you say automatically. I name my methods in such a way as you know what it does and returns straight away.

The reason I think this is bad as I do databases the same way. I can go from UNF-3NF pretty easily without being able to explain the steps in between.

@cmarshall10450 that's not bad. You are providing good context for what the function does. Your function name should express what it does clearly as long as you are not including any hints to how you are implementing the operation: lets say you have a stack that is named jobs. Then addJobToStack() would be bad because you are giving away the data structure you are using. You could easily just say addJob()

I agree with you that it should not be named that way. I much prefer addJob() over addJobToStack(). That is too verbose and is inflexible. Describing the data structure in the method name does not allow the method to be altered to return a different data type.

If I knew that the method would only be used in the context of jobs I'd call I'd "add" to avoid jobs.addJob()

As I'm just at the end of a computing degree and haven't had any real world experience I feel that my ideas are more than likely wrong. Any advice or feedback is greatly appreciated

Sure, the perfect Code/Programming Language should explain itself, but sometimes it is too complex. See SQL, designed to be easy to read, but finally nah you know, it is quite far from this Intention.

@cmarshall10450 well yes and no. The main reason you don't want to expose the data structure you are using in a method is for security reasons. It violates data hiding principles. But also if you decided to implement the function in a different way later then you would be forced to rename the function as well which is bad.

@cmarshall10450 and I should've used queue as the example data structure because push() is already a conventional naming for adding something to a stack. Queue is even used for prioritizing "jobs" so just pretend I said queue and not stack

@Daydream it's not about the language, it's about you being a professional and using the language you are given as clear and clean as possible; even if you have to work around some of its pitfalls.

Exactly... Hide yourself ... Otherwise it will shameful.... Rework on it and make it better later...

@kaqqao you should be naming your functions to provide good context for what it does. Naming properly is half the battle and I agree 100 percent with Martin.

For sure! Unless you know you'll be working with inexperienced developers, or you have some kind of unusual deadline (hackathon, showcase, etc). I think some people tend to take this as an axiom without putting thought into their own specific situation.

(ofc, if you touch the code after the deadline, clean it!)

@kaqqao i am assuming the class that the
getTwoLargePrimeNumbers() belongs to is well named then you can add the comment outside of the method. We are talking about commenting inside the method; there's a difference.

Generally speaking I whole-heartedly agree with Robert. That being said, I agree that there are some scenarios where comments explaining 'why' something is done make a lot of sense (especially in scenarios where you have to use less-than-obvious code for performance reasons).

Also comments that become documentation for an API are acceptable (XML doc, jsdoc, swagger doc, etc.)

@kaqqao and just to be clear, I never claimed anywhere that comments should never be used. They should be minimized. What's the ratio of functions you would have to explain that explicitly with comments to ones that you don't? I bet very very very small. Either way this isn't law and if you disagree you disagree. If you are maintaining a large project with tons of comments like the one you mentioned above than good for you.