259 votes
Accepted

Why does Uncle Bob suggest that coding standards shouldn't be written down if you can avoid it?

There are a few reasons. Nobody reads documentation. Nobody follows the documentation even if they do read it. Nobody updates the documentation even if they do read it and follow it. Writing a list ...
Stephen's user avatar
  • 8,848
174 votes
Accepted

Coding standard for clarity: comment every line of code?

Michael Durrant's answer is IMHO not bad, but it is not literally answering the question (as he admitted by himself), so I'll try to give an answer which does: I also understand that comments should ...
Doc Brown's user avatar
  • 207k
154 votes

Coding standard for clarity: comment every line of code?

Major anti-pattern leading to poor quality code with less clarity btw readers, the title was originally "comment every line of code?" and you can imagine the instinctive reaction of many of us, ...
Michael Durrant's user avatar
116 votes

Why does Uncle Bob suggest that coding standards shouldn't be written down if you can avoid it?

There's another interpretation. I don't believe it is what Uncle Bob meant, but it is worth considering. Don't capture coding standards in a document. Capture it in code, by having an automated ...
Tom Johnson's user avatar
  • 1,039
111 votes

Why do so many standards for JSON API response formats contain a "success" property in the response body instead of just using HTTP status codes?

Many people take HTTP status code as “successful communication with the server”. Now if a customer wants to buy a US$200 item and has only US$100 in their account, the JSON response will be “failure, ...
gnasher729's user avatar
  • 45.4k
101 votes
Accepted

Is this use of a symbolic constant overkill?

IMHO your friend is right in using a symbolic name, though I think the name should definitely be more descriptive (like BOARD_WIDTH instead of CHESS_CONST). Even when the number will never change ...
Doc Brown's user avatar
  • 207k
100 votes
Accepted

Is using parameter names that differ from type names only by casing considered a bad practice in C#?

Don't overthink this, Range range is fine. I use such kind of naming for more than 15 years in C#, and probably much longer in C++, and have never experienced any real drawbacks from it, quite the ...
Doc Brown's user avatar
  • 207k
100 votes
Accepted

How can I avoid always feeling like if I completely rebuilt my program from scratch I'd do it much better?

This is a very common experience Most people I interact with, and I myself as well, feel like this. From what I can tell one reason for this is that you learn more about the domain and the tools you ...
Andreas Kammerloher's user avatar
80 votes
Accepted

Adding Units To Magic Numbers

The issue is not only with the lack of units, but the fact that it is not clear what three of those units represent. Do you only have three minutes to complete a task? Then the constant might be ...
Vincent Savard's user avatar
70 votes

Why does Uncle Bob suggest that coding standards shouldn't be written down if you can avoid it?

People overlook the real purpose of a coding standards document, which is to settle disputes. Most of the decisions in the coding standard will have only a very minor effect on readability and ...
pjc50's user avatar
  • 13.4k
68 votes
Accepted

Is it enough for methods to be distinguished just by argument name (not type)?

Sure there is a good reason to name it more explicitly. It's not primarily be the method definition that should be self-explanatory, but the method use. And while findById(string id) and find(string ...
Kilian Foth's user avatar
62 votes
Accepted

Why does software use the Win32 name?

Win32 is the customary name for the Windows API. This API specifies how applications can interface with the operating system. It is roughly comparable with the POSIX standard on Unix, but Win32 also ...
amon's user avatar
  • 134k
59 votes

Is a JS Boolean having custom properties a bad practice?

Congratulations, you've discovered objects. The reason not to do this is called the principle of least astonishment. Being surprised by a design is not a good thing. There is nothing wrong with ...
candied_orange's user avatar
58 votes
Accepted

Why do so many standards for JSON API response formats contain a "success" property in the response body instead of just using HTTP status codes?

A few potential reasons why you may wish to do this are: the fact that some HTTP clients treat anything other than 2xx as an "exception" to be thrown, which can hide differences between ...
AIWalker's user avatar
  • 1,307
45 votes

How can I avoid always feeling like if I completely rebuilt my program from scratch I'd do it much better?

Learn refactoring - the art of gradually improving code. We all learn all the time, so it is very common to realize that the code you have written yourself could be written in a better way. But you ...
JacquesB's user avatar
  • 59.6k
44 votes
Accepted

Do you generally send objects or their member variables into functions?

Neither is generally better than the other. It's a judgment call you have to make on a case-by-case basis. But in practice, when you're in a position that you can actually make this decision, it's ...
Ixrec's user avatar
  • 27.8k
41 votes
Accepted

Should I really use all uppercase for my constants?

You are probably writing code like this: notes_director = argv[1] chdir(notes_director) files = glob('*.txt') rand_file = choice(files) with open(rand_file) as notes_file: points = notes_file....
Winston Ewert's user avatar
40 votes

Should coding best practices always be used

Should coding best practices always be used Always? No, that's silly. Best practices are guidelines. For most people, for most situations, if implemented with some finesse, they will yield the best ...
Telastyn's user avatar
  • 109k
40 votes
Accepted

Is a JS Boolean having custom properties a bad practice?

In addition to the general design principles, like single responsibility, and least surprise, there's a JavaScript-specific reason that it's not a good idea: there's a huge difference between a ...
Matthew Crumley's user avatar
39 votes

Does a `long` ban make sense?

No, banning the builtin integer types would be absurd. They should not be abused either, however. If you need an integer that is exactly N bits wide, use std::intN_t (or std::uintN_t if you need an ...
5gon12eder's user avatar
  • 7,196
35 votes

Is it enough for methods to be distinguished just by argument name (not type)?

Advantages of FindById(). Future-proofing: If you start with Find(int), and later have to add other methods (FindByName(string), FindByLegacyId(int), FindByCustomerId(int), FindByOrderId(int), etc), ...
Peter's user avatar
  • 3,748
34 votes

Should I really use all uppercase for my constants?

Yes. According to PEP8s rule on constants: Constants are usually defined on a module level and written in all capital letters with underscores separating words. Examples include MAX_OVERFLOW and ...
Thomas Junk's user avatar
  • 9,543
30 votes

Why does software use the Win32 name?

Because the Windows API is 30+ years old and has been around when PC's were 16-bit, then 32-bit came along, then Win32s, then win64. There is platform dependence in windows development, and you need ...
Thomas Carlisle's user avatar
30 votes

Is it bad practice create "alias" variables to not use globals or arguments with long names in a method?

In general, creating local variables for readability is a good thing. A local variable gives a locally relevant name to something; that same thing might have a different name in a different context. ...
IMSoP's user avatar
  • 5,857
29 votes

Should coding best practices always be used

Yes. That is self-evident. Why would you not do what is best? That's not the issue though. The hard part is finding out what IS the best practice, because in order to answer that you need to know ...
sara's user avatar
  • 2,559
28 votes
Accepted

Is scientific code a different enough realm to ignore common coding standards?

Is scientific code a different enough realm to ignore common coding standards? No, it's not. Research code is often "throw away" and written by people who are not developers by background, however ...
enderland's user avatar
  • 12.1k
28 votes

Do you generally send objects or their member variables into functions?

This isn't an exhaustive list, but consider some of the following factors when deciding whether an object should be passed to a method as an argument: Is the object immutable? Is the function 'pure'?...
Ben Cottrell's user avatar
  • 11.8k
28 votes
Accepted

Why did JUnit declare setUp and tearDown in camelcase, even though each of them is a single word?

No, it shouldn't. For the moment, there is still a difference between the noun "setup" and the verb "set up": Hey Joe, can you set up the amp for me? Dude, that's a sweet stereo ...
Kilian Foth's user avatar
25 votes
Accepted

Use `ref` merely for clarification?

No. For anyone who has understood what the ref keyword means, this obfuscates what the method really does. The better alternative is to pick a more descriptive name for such a method like ...
Doc Brown's user avatar
  • 207k

Only top scored, non community-wiki answers of a minimum length are eligible