I had to read some book on code architecture for a CS class a few years back and it was just 200-300 pages of this shit. Academics push dogma because they have never shipped successful software or been exposed to the real world so it's all they know. I specifically remember one chapter where the author discussed how, under tight deadlines, software developers are more likely to write hacky code. His solution? Don't write bad code and always take the time to write good code even if you're on a deadline.
sicp is a better code architecture book than this kind of "ALWAYS DO THIS THING NEVER DO THAT THING JUST WRITE GOOD CODE TO GOOD CODE WRITE" shit
it's called
structure and interpretation of computer programs for a reason
generally bad and should not be used at all.
this statement can be found on the "top 10 most dangerous things to say" list on watchkiwi.farms
If you can't read what the code does from function and variable names then comments is just a bandaid. It should mainly be for arbitrary looking code order that switching would fuck things up, and algorithms/important optimizations where trying to pretty it up would fuck performance but you'd really want to know why you did something in a few months.
correct. i don't think they're as bad as this thread seems to be making them out to be, however. "a++; // adds 1 to a" is retarded but most comments are far less superfluous. while the ideal piece of code is perfectly readable with 0 comments, note how rare ideal pieces of code happen to be in the real world. banning them would be the most retarded "style rule" since the nigger who invented the "multiple returns BAD" rule
they are nice at the top of function declarations, so that text editors can display a short snippet of online help to jog people's memory and maybe clarify a few things. sometimes, even the best naming can still not provide certain information:
Similar a C:
/* Create a squad. The value of maxUnits should be 6 or less,
since the enemy soldier AI is awfully quadratic and ends up far more
expensive than we want for big squads. */
Squad createSquad(TeamFlags team, int maxUnits);
// ... (doesn't need a comment (or can have something trivial))
void addUnitToSquad(Squad squad, Entity unit) throws SquadFull or whatever;
these are a couple functions for a hypothetical video game that lets the player have up to 3 allies and spawns enemies in squads of up to 6 members, but it could spawn bigger ones for certain set pieces or something like that. i personally believe comments like these are quite acceptable
they are also pretty good in situations where you're doing complicated setup or something, and there are multiple distinct "phases" in the code; while you
could make a new function, it's usually a functionality only used in 1 place and so you can instead just make a comment with what the function's name would be if it was a function
of course the above remark is tailored for c-like languages: if you're using a language with first-class lexical closure, you could just declare a few well-named functions inside the big function and then call them in sequence, accessing the various variables directly, which would be about as easy as just using comments and then it becomes a matter of your personal taste in aesthetics really
tl;dr: i think comments are quite nice in certain situations
relatedly, i think the "ideal style" actually can vary a lot depending on the language you're using and even with the specific problem you're solving. strictly following some rules dictated by some nigger who isn't currently solving your specific problem is only smart when the rules are always right at all times (rules about
style and how a program is laid out for ease of understanding? probably not!)
some of the rules are always right though (such as "yes, you have you indent your code, at the very least consistently throughout single functions")
Absolutely not. Fuck off asshole. We have Intellisense. We don’t need this bullshit anymore. Either it’s going to be so short that it isn’t useful, or it’s so long that it bulks up the code and makes scrolling hell. It has to be kept up-to-date, and you need access to the code (or at least the header) to update it.
Putting your documentation in code is like putting style in HTML tags. You’re mixing domains that shouldn’t be mixed. Code should be code and documentation should be documentation. They should not be put together. We look down on hardcoded numbers, why the hell do we not look down on hardcoded descriptions of what we think the code is doing?
some people like the inline documentation popups
cease this nonsense it is like a spaces vs tabs flamewar
out! how nice!"
