173
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 ...
- 214k
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, ...
- 13.3k
136
votes
Accepted
Naming of bool methods: Is vs. Can vs.?
Is vs. Can
According to the Microsoft naming convention recommendations, both "Is" and "Can" are OK (and so is "Has") as a prefix for a Boolean.
In plain English, "Is" would be used to identify ...
- 26.9k
90
votes
Python file naming convention?
Here is a link for different types of Python name conventions.
The style guide for Python is based on Guido’s naming convention recommendations.
- 1,011
68
votes
Best Practice - Avoid naming class and field the same?
Bart van Ingen Schenau has some good advice, but I'd like to offer some additional advice.
Don't universally avoid naming a class and property the same, but definitely question it. Consider all of the ...
- 41.9k
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 ...
- 135k
40
votes
Why are module-specific prefixes widely used for function names in C modules?
Why prefixes in the first place?
The prefix for function names is a C practice that intends to avoid naming conflicts.
This is especially suitable in big projects, where different teams could easily ...
- 80.6k
40
votes
Best Practice - Avoid naming class and field the same?
Fields/properties/attributes within a class should describe something of the concept that you are modelling with that class. You should be able to ask questions like "What is the <property> ...
- 76.7k
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 ...
- 1,343
28
votes
What form of verb to use (imperative verb or third-person verb) in programming?
var val = obj.GetValue();
var val = obj.PlayOnAwake; // From Unity
It's not first-person, it's imperative. Simply put, it's a command.
GetValue() Get the value!
PlaySound() Play this sound!
...
- 56.3k
24
votes
Coding standard for clarity: comment every line of code?
I don't think a coding standards document is the place to specify what is already common sense. The purpose of a coding standard is to guarantee consistence (and avoid arguments) about issues where ...
- 61k
24
votes
C# - Why are prefixes on fields discouraged?
When they were working on the API for Windows, Microsoft recommended the use of Hungarian Notation, using 'm_', as well as 'i', 'sz', etc. At the time, this was useful because the IDE wasn't robust ...
- 2,837
24
votes
Accepted
How to name a Boolean variable that represents either of two options?
Don't use a Boolean. Use an enum. E.g TransactionType with instances Buy and Sell.
That is unambiguous and far easier to understand.
If you want to persist the data efficiently, the boolean can be a ...
- 4,628
23
votes
Why does convention say DB table names should be singular but RESTful resources plural?
The REST spec (whatever level you want to go with) wasn't designed as database access. It is trying to bring standardization to API access. The SQL conventions mentioned (whether you want to use them ...
- 4,401
23
votes
Accepted
How to name uppercase variables when using the camelCase convention?
At least going by .NET naming guidelines, you should use _apiEndpoint if it is a field or ApiEndpoint if it is a property. Quoting from the link:
The PascalCasing convention, used for all identifiers ...
- 427
22
votes
How should I name functions that return values in Python?
Use verbs where reasonable, nouns if they are shorter and unambiguous
Most of the time, functions should be (imperative) verbs and classes, variables, and parameters should be nouns. Attributes ...
- 2,668
20
votes
Coding standard for clarity: comment every line of code?
It is not possible. What you are essentially trying to do is nearly to mechanize good judgment.
When writing critical software such as for life supporting medical systems, huge amounts of checklists ...
- 27.7k
20
votes
Naming of bool methods: Is vs. Can vs.?
It's worth mentioning that the "should" prefix can also be used. According to Apple's guideline, not just "can" and "should", modal verbs in general can be used to name functions that return boolean. ...
- 225
20
votes
Accepted
Is it a good practice to end a function's name with a preposition?
If it adds meaningful clarification or fits the "ethos" ... Yes.
.NET's OrderBy() and ElementAt() might be good examples.
Personally, I like code that reads pretty much like English. It takes a ton ...
- 15.2k
17
votes
Why are module-specific prefixes widely used for function names in C modules?
There are two important types of naming collisions here. You are correct in that the compiler won't have any trouble differentiating between the functions due to scope rules. Your problem is that ...
- 1,161
16
votes
C# - Why are prefixes on fields discouraged?
C# doesn't have any global variables, so that leaves only local variables and class-fields.
And if you have so many local variables you lose track of whether an identifier is one, you have most ...
- 9,131
16
votes
Why are module-specific prefixes widely used for function names in C modules?
There is another reason to use prefixed names even for file-local functions: they can be navigated with simple text search and text indexers without full analysis of language scoping, such as id-utils....
- 2,585
15
votes
Accepted
What is the best practice when it comes to naming microservices?
Reading your question I'm not sure you are thinking about microservices in the same way as me.
For example I would never create a validation microservice. In theory, sure I can see it might work, but ...
- 79.8k
15
votes
Accepted
What's the Java convention for names with a sequence of numbers, like "ISO 8859-1"?
Guidelines are guidelines, not immutable laws of nature. You have found an excellent example of a sensible name that cannot be easily mapped into the normal Java naming conventions. So what should you ...
- 135k
15
votes
Method naming: to vs as vs get
The term as is often used to denote that the method casts the item from one type to another, without creating a new object.
The term to often indicates that the method creates a new representation of ...
- 39.5k
14
votes
Use of "my" prefix in object naming
Sounds like the author has been cutting and pasting code examples, which commonly show classes that begin with My in order to illustrate that they are written by the individual (as opposed to ...
- 26.9k
14
votes
Accepted
Naming convention for Boolean arguments
The typical is/has/can prefixes make sense grammatically in the context of an object. Given an object x, we can say that “x is something”, that “x has something”, or that “x can do something”. Having ...
- 135k
13
votes
Coding standard for clarity: comment every line of code?
Update
My response in quotes for emphasis:
It is my belief the answer that states the comments should not be addressed in Coding Standards and then lists a set of defensive questions to fight it, is ...
- 3,122
13
votes
Coding standard for clarity: comment every line of code?
There are two different things you allude to when you talk about comments. They're not the same, and the distinction is important.
Documentation tells you about the outward-facing bits of a piece of ...
- 1,693
13
votes
Accepted
Are there historical problems with non-ASCII identifier characters in code?
There are historical reasons for this guidance, that are mainly related to the lack of uniform encoding standard.
Encoding issues
Unicode dates back to the 90s'. Before it became mainstream, there was ...
- 80.6k
Only top scored, non community-wiki answers of a minimum length are eligible