Please please please, do not always write comments. Try to write code that does not need comments whenever possible. Proper variable, class and method names go a long way. If you think a block of code needs a comment, turn it into a method and give it a proper name instead.
Comments should be a last resort for cases where making the code self explanatory is not possible, and those should be rare.
About optimization:
Optimal code is code that fulfills it’s purpose without observable issues.
If you try to make something faster without any prior complaints or measurements indicating that it being slow is an actual issue, you are not optimizing, you are just engaging in mental masturbation.
For my current job we’ve all agreed to take the approach of not writing comments that say what the code does, but why you did something the way you did. Probably about 90% of our code is uncommented because it just doesn’t need to be, but every once in a while you have to do something out of the ordinary to get the desired behavior, and explaining why you made the weird decision you did is infinitely more helpful.
This exactly. I love this approach to commenting and use it all the time. I also like to write doc-comments wherever possible; it’s saves time and makes working on an unfamiliar part of the codebase much easier.
I just get AI to write my comments lol. I’ll paste the function or component and tell it to write comments in tsdocs format and it works great every time (I will also add to it sometimes of course).
Don’t get me wrong, I also write clean code with good function and variable naming, but I find comments are also useful for a few reasons; they make the code even more quickly readable, they can explain why the code is the way that it is, and my favorite reason, they make it so when you hover over a reference to the commented item in an ide you get an explanation of exactly what the code does and what it expects without having to find and read the code itself
The problem here is that every junior programmer thinks they write clean code when they really really don’t. Often I find the act of writing comments makes you go back to the code and clean things up, so it’s still worth encouraging comments.
I strongly disagree with the comments. “The code is the documentation” was a dumb joke about being to lazy to write documentation, not a best practices guideline.
Proper naming is good, but there are a lot of issues with not commenting code. Obviously it’s dumb to comment every line, but it’s really useful to comment functions/methods, because otherwise you never know if something’s a bug or a non-obvious feature. Comments act as a parity check to the code, since they tell you what the dev who wrote the code wanted the code to do.
Also, everone thinks they write good, clean and obvious code. Hardly anyone purpously writes bad, hacky code. Yet if you look at code you wrote a year ago, or code someone else on your team wrote, it’s full of non-obvious hacks. That means, people constantly misjudge the obviousnes of their code. Comments should be put on anything that could maybe be non-obvious.
And putting documentation of the code anywhere else than in a comment (e.g. Confluence) is a total waste of time (unless you put a link to the specific page of the documentation in a comment in the code), because documentation that you don’t directly see without effort will not be found and not be read.
it’s really useful to comment functions/methods, because otherwise you never know if something’s a bug or a non-obvious feature. Comments act as a parity check to the code, since they tell you what the dev who wrote the code wanted the code to do.
Unit tests should be the parity check for other code. Those don’t get outdated with the next refactoring where someone didn’t remember to also adjust all the comments.
Also, everone thinks they write good, clean and obvious code. Hardly anyone purpously writes bad, hacky code. Yet if you look at code you wrote a year ago, or code someone else on your team wrote, it’s full of non-obvious hacks. That means, people constantly misjudge the obviousnes of their code. Comments should be put on anything that could maybe be non-obvious.
Why would people be better at judging if something needs a comment than at judging if something needs a better name or refactoring? Asking people to skip that judgement step and comment everything just gives you a bunch of useless boilerplate comments. That trains everyone reading that codebase to ignore comments because they are almost always useless anyway.
putting documentation of the code anywhere else than in a comment (e.g. Confluence) is a total waste of time
At least this we can 100 % agree on. Documentation should be as close as possible to the code. (I just think most of the time that place is in the name of things, not in an actual comment.)
You can’t be too obvious when writing code. Good names, good code structure, unit tests and comments are not mutually exclusive. And comments are the cheapest part of all of that. Commenting what a method does takes a fraction of the time that good code structure or unit tests take, so adding a comment is rarely not worth the effort.
Why would people be better at judging if something needs a comment than at judging if something needs a better name or refactoring? Asking people to skip that judgement step and comment everything just gives you a bunch of useless boilerplate comments. That trains everyone reading that codebase to ignore comments because they are almost always useless anyway.
Again, who is asking them to skip judgement? I am saying, do comments additionally.
And forcing programmers to do anything they don’t understand or are against will always result in useless results. I’ve seen enough unit tests that don’t actually test what the tested code does. I’ve seen nonsense comments. I’ve seen naming that “follows” the guideline but is totally useless or even wrong. I have even seen code that was implemented in spite and where the code superficially checks all the boxes but is totally terrible once you peek beyond that. Same goes for the whole process. If a programmer doesn’t care for code reviews, you get nothing by forcing the programmer to do them.
Does this mean all of these things are useless, just because programmers can purpously sabotage them and find loopholes that fit the guidelines? I don’t think so.
At least this we can 100 % agree on. Documentation should be as close as possible to the code. (I just think most of the time that place is in the name of things, not in an actual comment.)
If you can fit all the information about what something does plus all the specifics, edge cases, non-obvious things and the reason why this specific approach was taken in maximum 4 words, then yes. Otherwise comments are the way to go.
Having no documentation is fine for a small project with one dev that will get tossed in a year. But if you are making something that will actually be used for longer, than it’s not ok.
If you’re writing an explanation of what your code does then, ding ding, you’re writing code. If your code has so many side effects and garbage in it that it’s incomprehensible without an explanation then it’s shit code and I doubt you’d be able to write a comment that explains it that is not equally as shit as the code. Commenting on how shit code works cannot be trusted because the commenter has already proved they’re shit at the job by creating that shit code.
Best you can hope for is the comment contains a reason as to why the code is shit.
“Code is the documentation” is the paradise we all want to be someday. But some people use that as an excuse to not write the documentation explaining why this piece of code exists in the first place. I find it extremely annoying when there is not a single architecture diagram is available and someone tell me to figure it out by reading his/her spaghetti code.
The problem is that code is language and people who write shit code tend to write shit comments, so no value is gained anyway. The sort of person who’d write good comments will most likely write good code where these comments are not needed, and when they intentionally write shit code they’d probably explain why.
So best you can hope for is that both of these people write comments about why they decided to write a comment, and hopefully the person who writes shit code improves over time.
This is the way. In ‘some’ cases comments are perfectly fine. Like when you need to document ‘why’ something was done the way it was our to link to a specific piece of documentation.
When you start commenting ‘what’ the code does, you code is not self explanatory enough. And those comments will get outdated and need refactoring too. Just more unnecessary work.
If you think a block of code needs a comment, turn it into a method and give it a proper name instead.
Really depends. Yes, if someone doesn’t get what’s wrong with this statement, they should. But you shouldn’t wrap something in a method all the time just because. Sure, maybe you can make it an inline method, but usually, a method call takes time, and while it’s not a lot of time, in constrained or complex system that can accumulate. A lot. Sure, the compiler might optimize stuff away, but don’t just go blindly trusting your compiler.
Sure, a method call for something that gets called once a second is not a problem. But when you suddenly have thousands and thousands of method calls when say, you click a button, which calls method x which calls method x1 which calls y1 and y2 which call z1-10 and so on, then the method calls can suddenly turn into a problem.
Maybe not on a fast, modern device, but on an older or more constrained device. If your code never runs on there, sure, don’t bother.
It depends on how badly you need to use the site. If you need it and it’s your site, it’s a lot better because you can fix it. If you don’t need it, you still have to fix it if it’s yours, but you can just walk away if it isn’t.
Don't write comments for someone else. Write comments for yourself because you might write a million lines of code and then be told you need to do something to this now ancient legacy code at 3am because some nightmare scenario happens and you need to get it fixed and deployed before they'll let you go back to sleep.
Yeah, this grinds my gears. I use to comment my code when I'm working on my personal projects, then at the office I have to waste time trying to decipher my boss's code because he won't comment absolutely anything.
That plus the ridiculous deadlines means that I don't have time to comment my own code, fast forward several months later without working on a particular project and now I have to decipher his and my own code.
One day he actually had the nerve to say to me: 'Yeah, you should comment your code'. How I refrained of commiting murder that day I don't know.
Doubles have a much higher max value than ints, so if the method were to convert all doubles to ints they would not work for double values above 2^31-1.
(It would work, but any value over 2^31-1 passed to such a function would get clamped to 2^31-1)
To avoid a type conversion that might not be expected. Integer math in Java differs from floating point math.
Math.floor(10.6) / Math.floor(4.6) = 2.5 (double)
If floor returned a long, then
Math.floor(10.6) / Math.floor(4.6) = 2 (long)
If your entire code section is working with doubles, you might not like finding Math.floor() unexpectedly creating a condition for integer division and messing up your calculation. (Have fun debugging this if you’re not actively aware of this behavior).
Yeah it makes sense to me. You can always cast it if you want an int that bad. Hell just wrap the whole function with your own if it means that much to you
How does that work? Is it just because double uses more bits? I’d imagine for the same number of bits, you can store more ints than doubles (assuming you want the ints to be exact values).
No, I get that. I’m sure the programming language design people know what they are doing. I just can’t grasp how a double (which has to use at least 1 bit to represent whether or not there is a fractional component) can possibly store more exact integer vales than an integer type of the same length (same number of bits).
It just seems to violate some law of information theory to my novice mind.
I’m going to guess here (cause I feel this community is for learning)…
Integers have exactness. Doubles have range.
So if MAX_INT + 1 is possible, then ~(MAX_INT + 1) is probably preferable to an overflow or silent MIN_INT.
But Math.ceil probably expects a float, because it is dealing with decimals (or similar). If it was an int, rounding wouldn’t be required.
So if Math.ceil returned and integer, then it could parse a float larger than INT_MAX, which would overflow an int (so error, or overflow). Or just return a float
I don’t think that’s possible. Representing more exact ints means representing larger ints and vice versa. I’m ignoring signed vs. unsigned here as in theory both the double and int/long can be signed or unsigned.
Edit: ok, I take this back. I guess you can represent larger values as long as you are ok that they will be estimates. Ie, double of N (for some very large N) will equal double of N + 1.
I would need to look into the exact difference of double vs integer to know, but a partially educated guess is that they are referring to Int32 vs double and not Int64, aka long. I did a small search and saw that double uses 32 bits for the whole numbers and the others for the decimal.
Okay, so I dug in a bit deeper. Doubles are standardized as a 64 bit bundle that is divided into 1 signed bit, 11 exponetioal bits and 52 bits for decimal. It’s quite interesting. As to how it works indepth, I probably will try to analyze a bit conversion if I can try something
You can think of a double as having a fixed precision, but, in contrast to an integer, this precision can be moved over the decimal point depending on the value you want to represent. Therefore, despite representing floating-point numbers, a double still has discrete steps determined by its binary representation of 64 bits. If the value of a double gets larger, it reaches a point where the smallest difference between two subsequent doubles is greater than one. For float (32 bit), you reach this point at 16777216. The next larger number to be represented as a float is 16777218 (i.e., +2).
I agree with all that. But I’m talking about exact integer values as mentioned in the parent.
I just think this has to be true: count(exact integers that can be represented by a N bit floating point variable) < count(exact integers that can be represented by an N bit int type variable)
It doesn’t. A double is a 64 bit value while an integer is 32 bit. A long is a 64 bit signed integer which stores more exact integer numbers than a double.
Technically, a double stores most integers exactly ( up until a certain value ) and then approximations of integers of much larger sizes. A long stores all its integers exactly but cannot handle values nearly as large.
For most real world data ranges, they are both going to store integers exactly.
Also because if you are dealing with a double, then you’re probably dealing with multiple, or doing math that may produce a double. So returning a double just saves some effort.
A double can represent numbers up to ± 1.79769313486231570x10^308, or roughly 18 with 307 zeroes behind it. You can’t fit that into a long, or even 128 bits. Even though rounding huge doubles is pointless, since only the first dozen digits or so are saved, using any kind of Integer would lead to inconsistencies, and thus potentially bugs.
Java has many abstractions that can be beneficial in certain circumstances. However, it forces a design principle that may not work best in every situation.
I.e. inheritance can be both unnatural for the programmer to think in, and is not representative of how data is stored and manipulated on a computer.
You don’t have to use inheritance with Java. In fact, in most cases it’s better that you don’t. Practically all of the Java standard library doesn’t require the use of inheritance, same with most modern libraries.
On the contrary, I think inheritance is a very natural way to think. However, that doesn’t translate into readable and easy to maintain code in the vast majority of the cases.
I am not sure what you mean by how it’s stored or manipulated on a computer. A garbage collected language like Java manages the memory for you. It doesn’t really care if your code is using inheritance or not. And unless you’re trying to squeeze the last drops of performance out of your code, the memory layout shouldn’t be on your mind.
People hating on Java because “inheritance” usually don’t know the difference between inheritance and polymorphism. Stuff like composition and dependency inversion is black magic to them.
We’re gate-keeping the most mainstream programming language now? Next you’ll say English isn’t a real language because it doesn’t have a native verb tense to express hearsay.
And it is not forced at all. Noone holds a gun to your head to write extends. “Favor composition over inheritance” has been said as a mantra for at least a decade
Memory is an implementation detail. You are interested in solving problems, not pushing bytes around, unless that is the problem itself. In 99% of the cases though, you don’t need guns and knives, it’s not a US. school (sorry)
I do not like Java but this is a strange argument. The people that invented Java felt that most of the C language should be wrapped in unsafe.
Opinions can vary but saying Java is not a real language is evidence free name calling. One could just as easily say that any language that does not allow you to differentiate between safe and unsafe baheviour is incomplete and not a “real” language. It is not just the Java and C# people that may say this. As a C fan, I am sure you have heard Rust people scoff at C as a legacy language that was fine for its day but clearly outclassed now that the “real” languages have arrived. Are you any more correct than they are?
programmer_humor
Newest
This magazine is from a federated server and may be incomplete. Browse more on the original instance.