Good code is self-commenting. Commenting = bad code

>Good code is self-commenting. Commenting = bad code.

Attached: 1506485353767.png (645x729, 90K)

t. pajeet

Sometimes the best way isnt the most verbose way.

I unironically believe this, though. When I'm reading other peoples' code, I tend to just ignore the comments unless the code itself really is so badly written that it can't be understood without them. Which is the exception.

Commenting is not bad unless it says what instead of why. Code should be simple and descriptive enough to be easily understood and most comments aren't necessary.

>Good code is self-commenting.

Yeah.. And you know whats even better? Good code and good comments.

// welcome to my "hello world" program!
// a "hello world" program is a program that prints the message "hello world"
// i'm gonna write it in c ^^

// first we need to include some files
// we use the #include directive to include stdio.h and stdlib.h
// stdio.h will give us the printf function and stdlib.h will give us the EXIT_SUCESS macro!!!!
#include
#include

// now that we have included our files, we have access to the printf function and the EXIT_SUCCESS macro!!!!!
// now we need to put an entry point to our program
// it's called main and can be in several different forms
// in our case, we will use the form where main takes no argument and returns and integer
// it doesn't need any argument because no interaction is needed to print "hello world"
// the integer returned is just a unix thing for errors
// we will return the EXIT_SUCCESS code meaning that everything was fine
// so the syntax in c is int main(void) to say that the main function returns an integer and takes nothing
int main(void)
{
// now we're in the function
// use the function printf provided by stdio.h to print a message
// normally, printf takes several arguments to format the text with variables, bt we don't need it
// we could use puts instead, but it's not very standard and the compiler will optimize it anyway
printf("hello world\n");

// now we must return the "no error" code
// its value is EXIT_SUCCESS because there was no error
return EXIT_SUCCESS;

// and that's it
}

// out of the function
// so what do you think of this high quality, well-documented code?

Attached: cs graduate.jpg (2361x2167, 275K)

Worst argument ever

>no OwO

ya blew it

int i,j,k,l,m,n,o; /* variables */

kys

This is the way retards think: That they know what good code is because they can read it. This retard mentality would only work if we were all a hive mind. I can write "good code" to my standards, and make it impossible to read. Who defines "good"? I wanna meet them.


Commenting helps with collaboration because no two programmers are the same. If comments weren't necessary, they wouldn't exist.

Some kid said that in my class and the prof was just like aight that's cool

I love when kids yell shit and the professor is just like, "what evs" while knowing the kid will fail.

Good code is efficient, not necessarialy self commenting

#include
#include

int christina(int m, int n) {
if(m == 0) {
return n + 1;
}
if(m > 0 && n == 0) {
return christina(m - 1, 1);
}
if(m > 0 && n > 0) {
return christina(m - 1, christina(m, n - 1));
}
return -1;
}

int main(int argc, char** argv) {
int result = christina(4, 2);
printf("Result = %d\n", result);
return EXIT_SUCCESS;
}

Let's see you guess what this does WITHOUT an explanation, hotshot.

Attached: 5e7d2681f41320c669f59325845d3b7b64556d26_full.jpg (184x184, 7K)

>This retard mentality would only work if we were all a hive mind. I can write "good code" to my standards, and make it impossible to read.
Since others can write code that I can read without comments, that's some kind of standard. Don't go projecting onto others the fact that you can't read code without having English-language explanations.

>If comments weren't necessary, they wouldn't exist.
It's not like they're completely superfluous. For one thing, I do use comments when the code cannot really document itself, such as when it's working around problems outside the system, but that's pretty rare. They're also quite useful for delineating and organizing blocks within files.

On the opposite end of the spectrum, I absolutely hate reading eg. Java class library code, because it's so riddled with both comments and JavaDoc that it's often impossible to even fit more than one small function on the screen at one time.

Great code is both.

Fuck your comments. If you really want to modify my code you can fucking read through it and understand it before you fuck with it.

Comments encourage the user to just dive in and go OH LOL MUST B THIS LINE ILL JSUT CHANGE IT XDDDD without understanding the rest of the code.

This results in bugs. Comments should be reserved for truly cryptic shit. i.e. the mathematical formula you're performing, or more detail about a magic number. Of course public API documentation is good, but we're talking about comments in the middle of methods/functions I guess.

Only trivial glue code is readable by itself. When you are doing more complex algorithms you really need to at least document the inner functions for the sake of the reader.

>no meaningful variable names
Bad code.

Thats the ackermann function. Everyone knows what it does, brainlet.

>c program
>not a single c style comment, even though they would be more appropriate for those story columns

Point taken. It's much easier to understand with comments:
#include
#include
// calculates the christina value
int christina(int m, int n) {
if(m == 0) {
return n + 1;
}
if(m > 0 && n == 0) {
return christina(m - 1, 1);
}
if(m > 0 && n > 0) {
return christina(m - 1, christina(m, n - 1));
}
return -1;
}

// entry point for my app
int main(int argc, char** argv) {
// runs the "christina" routine
int result = christina(4, 2);
// print out the result
printf("Result = %d\n", result);
// let the OS know everything worked
return EXIT_SUCCESS;
}

You could begin by having a program that actually does something useful instead of just being recursion for its own sake, though, retard.

Also, intentionally obfuscating code isn't quite exactly the same thing as not commenting.
Finally, kill yourself.

Attached: retard-3-2.png (1190x906, 178K)

This is something I read in Clean Code, of course my coworkers all ate it up and think this is the best idea ever, but they were always too lazy to write comments. But now some "expert" said it so it's justified.

The arguemnt, that often comments aren't maintained is kind of true, but that's just because programmers are lazy, not because comments are bad.

>Not designing your algos with loosely described comments as a template and then filling in the actual code.

I shit you not.

For the love of GOD I hope you are never in charge of anything. Ever. Not even raising kids. You're saying that if you were presented with a complex driver design or a multi-functional project spanning across different languages that a team of people must use to create something, then comments would not be necessary because you can judge good code... I hope to god you're under the age of 25 with this retard mentality.

Then how comes I can go around debugging my Linux filesystem performance issues from the filesystem source code without reading the comments?
>Don't go projecting onto others the fact that you can't read code without having English-language explanations.

>confusing documentation of any sort for comments
Oh boy...

Comments depend on the audience, for a tutorial this would not be bad.

>OP says comments are useful
>Guy posts about comment
>other guy post more about comments

then...
you:
>uhh that's documentation
Please do your parents a favor and commit a belated self abortion. You'd be saving the world.

I'm not necessarily denying that with an increasing number of people on a programming project, the value of comments rises, doubly so if you're counting on some of them not being the brightest programmers around, but that doesn't mean that said value rises indefinitely. Comments also have intrinsic demerit in that they consume precious space and push other context off screen, and also in that they need to be maintained along with the code, so you are increasing your maintenance costs by overusing them.

If people like you were in charge, you'd probably make the compiler error out even if programs I just wrote for my own sake didn't contain at least 50% comment text. Please take your stupid activism to >>>/rust/.

Commenting is a skill too. Shit comments are as bad as shit code, except shit code is actually doing something.

I'm sorry, if your comments are pushing things off screen and wasting space, you're definitely a shit coder. I'd use Rust over any cancer you write any day.


Like how in the fuck are you writing comments that consume space and misalign things? I couldn't do something this stupid if I tried.

I seriously hope I never work with you. Comments are pushing things off screen in your code? I don't even think this is possible.

>If comments weren't necessary, they wouldn't exist.

me fucking your mom was not necessary either yet here you are

Code that can't be understood without comments is badly written. People who need comments to read the code either have low skill or don't know the architecture of the project, or both, and therefore should be prevented from contributing to the project. Writing the comments disrupts the programmer's flow, just like any frequent task switching does. Therefore, comments are harmful, q.e.d.

>Like how in the fuck are you writing comments that consume space and misalign things? I couldn't do something this stupid if I tried.
See eg. pic related from the Java class library. Literally over half the screen is taken up by uselessness.

Attached: ss.png (1594x1172, 25K)

Wow you sure showed me... How will I ever recover...

>Comments are pushing things off screen in your code? I don't even think this is possible.
I mean vertically.

Thats not pushing anything off screen or wasting space. You just don't like reading it. That is literally okayish commenting.

So fucking scroll you nigger, is that really that hard to do? Do you expect all programs to be "hello world" in length and simplicity?

You have to be unemployed to think this way.

>That is literally okayish commenting.
It's useless, because it's completely abundantly clear what the code does anyway. I mean, surely you aren't saying that you can't figure out this functionality from the code alone?
Now I know this is JavaDoc so it has another purpose, but it's not like this kind of commenting is completely unheard of, and I bet it's what you want every program to have.

>So fucking scroll you nigger, is that really that hard to do? Do you expect all programs to be "hello world" in length and simplicity?
No, but the more context you can see at one time, the better. Or would you be just as fine with an editor that displayed 5 lines at a time just because you can scroll anyway?
>You have to be unemployed to think this way.
I am in fact self-employed and making an actual income, thank you.

LISP interpreter written in LISP takes one line of code, everything simpler than an interpreter should take no more than one line of code as well. Software is incredibly bloated nowadays.

Documentation is good.
If you seriously think well documented methods are a bad thing, you should kill yourself. I bet you think man pages are bad too, LOL JUST READ THE SOURCE DOOD.

Documentation is good, but that was the first example I could think of to show the pains of abundant commenting, and also one of the reasons I don't like JavaDoc. I do in fact write documentation and manpages in particular, but I maintain them in separate files.

Hints the word "okay-ish" that commenting is a bit much, but I can see how someone could use it. You can't think for everyone, only for yourself. But I get it, you really really want to be "that guy that knows better than the devs that wrote it and the audience its written for."

I unironically like this. How can you go wrong with commenting? You dont even have to look at them theyre there for a worst case scenario.

The only people who make this statement are people who have no concept of documentation. Anything publicly exposed should be documented so that people using it do not need to read your code. If I use a library, I don't want to have to deep dive into all the shitty source code written by some dumbfuck just to learn how to use some public methods.

>self-employed.
Now I understand why you can't use comments.

>You can't think for everyone, only for yourself.
That's not an excuse for not even trying to learn to read code that isn't excessively commented.

Here's some advice: comments are optional to read. No one is making you read them.

Writing clean, readable, commented code makes you expendable. Replaceable. Generic.
If you get shit done and nobody knows how it works, nobody's gonna try messing with it and you enjoy job security until retirement.

Only 7 more years for me bros.

That's exactly what I'm saying is false, though. I might not be forced to read them, but:
>i'm forced to have them on my screen
>i'm forced to update them if i'm maintaining the program
Both of these are costs. Costs to be balanced with the perceived value of the comments, true, but the costs are non-zero.

m and n are pretty much universally used for natural numbers, only a pajeet would write number1 and number2.

1. You're not forced to have them on your screen. There are tons of plugins for every IDE that literally hides comments.

2. No shit. If you're maintaining software and a new developer is supposed to keep up-to-date with your changes because the original code is a obfuscation,

you know what.. I don't think you're that smart enough of a person to understand what any of this means... I'll just let you be retarded. The world keeps spinning...

>entry point for my app
>app

That's an interesting hypothesis, coming from a NEET. However, in the real world, if they don't like your code, they get rid of you pretty quickly. In the real world you work on a team and there is such a thing as "architecture review" and "peer review" and "confluence documents" and "application specifications". You'll understand when you are older.

You should document public API functions and write comments where the reasoning behind a section of code is not obvious.

Don't narrate your code as if the reader did not know the language.

found the boomer

>Hiding comments because there are too many
great, I get to choose between lots of random crap on my screen and not seeing the actual important bits.

Alternatively I could write comments only when there is something unusual that is not easily understood otherwise.

Its true, but you also have to rmember that just because you personally cant read it doesnt mean no one else can.

Also self-commenting doesnt mean no comments ever. It just means keep your variables, functions, objects, and whatever else well named and dont write overly complex code when simple code will do. You dont need to comment on every line you write though. Its all about keeping a good balance.

>2. No shit. If you're maintaining software and a new developer is supposed to keep up-to-date with your changes because the original code is a obfuscation,
You could also not make the original code an obfuscation. Just an idea.

Depends on how large a team you're working on, though. Not every project is a 200-man (((enterprise))) J2EE project.

This is wrong. There will always be external constraints in your code. Domain knowledge and business decisions that mean you have to do things for non-obvious reasons. If you don't document why then someone will cone along later, assume whoever wrote it was a brainlet, and "fix" it.

I've been doing it for over 25 years boy.

>using /**/ for comments that don't extend to a second line
kys you are self senpai

Nobody wants to read millions of lines of comments.

You should only need a comment when something unusual is going on, or if you want to draw the programmers attention.

>Who defines "good"?

Sensible naming, an idiomatic interface that is easy to use correctly, minimal complexity and of course correct behaviour are all very obvious and objective measures of "good".

>/* */
>one word

Ask me how I know you're not in FAANG

>faang
fuck off apple shill

I remember in my intro course to java the professor made us comment each function to explain what it does. Like i mean

//calls class change to see how much change the ticket machine should give
Ticketmachine.ticketmachinechange

-std=c90

Well duh, knowing what the code does and what the programmer actually intended is super useful for grading work

>Who defines "good"? I wanna meet them.
Me. I do. Hello. How can I help you?

Attached: 1206056250397.jpg (418x694, 346K)

No, I don't comment a code, because otherwise some pajeet will be able to ruin it.

char *combine(s, t)
char *s, *t;
{

int x, y;
char r[100];

strcpy(r, s);
y = strlen(r);
for (x = y; *t != '\0'; ++x)
r[x] = *t++;

r[x] = '\0';

return(r);

}

this
this was one of my completed exercises in a python intro book
# Sets "types_of_people" to integer 10
types_of_people = 10
# Sets variable "x" as string using variable "types_of_people"
x = f"There are {types_of_people} types of people."

# Sets variable binary to string "binary"
binary = "binary"
# Sets variable "do_not" to string "don't"
do_not = "don't"
# Prints string with variables "binary" and "do_not"
y = f"Those who know {binary} and those who {do_not}"

# Prints variable "x"
print(x)
# Prints variable "y"
print(y)

# Prints variable "x" with string
print(f"I said: {x}")
# Prints variably "y" with string
print(f"I also said : '{y}'")

# Creates variable "hilarious" with boolean "False"
hilarious = False

# Creates variable "joke_evaluation" with a string
joke_evaluation = "Isn't that joke so funny?! {}"

# Prints "joke_evaluation" with the boolean from var "hilarious"
print(joke_evaluation.format(hilarious))

# Prints first half of joke
w = "This is the left side of..."
# Prints other half of joke
e = "a string with a right side."

# Prints variables w and e
print(w + e)

# Line 30, line 21, line 19, line 11 and line 4.
# There are 5 places with a string nested inside a
# string through a variable.

Comments always lie, code is about expression through the language, etc.

Link the kernel module.

False dichotomy. Generally well written code IS self documenting, but there are many scenarios where comments are valid and useful.

Only functions and methods should be commended, a couple of lines at the top of them to explain what they accept, returns
and do. Comments in between the code are distracting, pointless and a sure sign that you should split that code.