260
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 ...
- 8,700
175
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 ...
- 194k
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, ...
- 13k
116
votes
Accepted
Why is the minus sign, '-', generally not overloaded in the same way as the plus sign?
In short, there aren’t any particularly useful subtraction-like operations on strings that people have wanted to write algorithms with.
The + operator generally denotes the operation of an additive ...
- 20.3k
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 ...
- 1,039
110
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, ...
- 40.5k
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 ...
- 194k
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 ...
- 194k
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 ...
96
votes
Accepted
When is it appropriate to make a separate function when there will only ever be a single call to said function?
The rationale behind splitting functions is not how many times (or how often) they will be called, it's keeping them small and preventing them from doing several different things.
Bob Martin's book ...
- 39.1k
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 ...
- 1,896
73
votes
Do I need to use an interface when only one class will ever implement it?
No, you don't need them, and I consider it an anti-pattern to automatically make interfaces for every class reference.
There is a real cost to making Foo/FooImpl for everything. The IDE may create ...
- 1,169
73
votes
Using compound statements ("{" ... "}" blocks) to enforce variable locality
It is indeed a good practice to keep your variable's scope small. However, introducing anonymous blocks into large methods only solves half the problem: the scope of the variables shrinks, but the ...
- 106k
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 ...
- 10.2k
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 ...
- 106k
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 ...
- 130k
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 ...
- 97.7k
57
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 ...
- 1,277
49
votes
At what point is it taboo to have loops within loops?
To a degree, I stopped taking this quote seriously at "Tabs are 8 characters". The whole point of tabulators is that they are not a fixed number of characters (if anything, a tab is one character). ...
- 8,745
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 ...
- 56.1k
43
votes
When is it appropriate to make a separate function when there will only ever be a single call to said function?
I think function naming is very important here.
A heavily dissected function can be very self-documenting. If each logical process within a function is split out into its own function, with minimal ...
- 11.8k
40
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 ...
- 27.5k
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 ...
- 108k
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 ...
- 6,926
39
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 ...
- 514
39
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....
- 24.6k
38
votes
Is the use of one-letter variables encouraged?
Properly naming things is hard. Very hard. If you look at it the other way, you can also take this to mean that properly named things are important. (Otherwise, why would you have spent the effort ...
- 101k
37
votes
Why is the minus sign, '-', generally not overloaded in the same way as the plus sign?
Because concatenation of any two valid strings is always a valid operation, but the opposite is not true.
var a = "Hello";
var b = "World";
What should a - b be here? There's really no good way to ...
- 81.9k
Only top scored, non community-wiki answers of a minimum length are eligible