Comments and Naming Conventions
- Intent giving names
- Abbreviations and short forms
These apply to name everything: variables, class names, methods, packages, etc.
When you have the semantic model fresh in your mind it’s easy to map your code onto it
It’s not hard to remember that a variable named “x” is the date a record was created and “y” the date it was deleted.
Leave clues that will allow you to rebuild the semantic model when you come back at a later time.
Source: Why your code is so hard to understand
Comments can lie. The code does not.
Ideally, your code should be so good that you do not require comments.
This might not be true in one case which is when you code something weird and required domain-specific explanation.
When something is non-obvious put a comment.
Like in Machine Learning, a choice of certain parameters or a certain step can be understood better by putting the link to the explanation/research paper in the comment. While reading just the code, it might not be obvious for the reader to understand what to make of it. (Source: Jeremy Howard fast.ai).
Similarly, if you are using an external API, you can mention it in the comments.
Sometimes, you might want to link to a specific piece of code, in that case, you might use the javadoc format
/** * @see String#toLowerCase() convertToLowerCase */
javadocs are interesting if you want to write good comments.
Intent giving names
Use pronounceable names
Variables should be named so that they make it clear what it contains.
Variable names should always be easy-to-read, be short yet meaningful, mixed case with a lower-case first letter English words.
b)Use plural names for arrays/collections of objects.
c) Constant (static final) variable names should be in all capital letters and separate words in the name with the underscore, i.e., PRIORITY_NORMAL,
Source: java coding-convention and cleancode
For matrix operations use row columns instead of y and x because in some languages matrix is treated as [y,x]
Source: Gayle Laakmann McDowell (Cracking the Coding Interview Book)
Abbreviations and short forms
Many people try to optimize for the vertical space of the screen but forget horizontal space.
This is kind of an exception to the above rule: for things that are very very common, short forms are better. (You also type less).
Just don’t short everything to be a single letter. Be small but descriptive.
Also, having a list of abbreviations used in your project readme/documentation can be helpful.
repo for repository
util for utility.
serv for service
len for length
dto for Data Transfer Object (pretty common)
Make sure you use the same abbreviations everywhere in your code aka one word per concept in all classes.
(Below examples are for method names)
In case you are trying machine learning, I guess this article is much better suited: Jeremy’s notes on fastai coding style
Magic numbers and strings
Any number or string in your code that isn’t immediately obvious to someone with very little knowledge.
Better to declare them in a separate constants file.
Constants should be snake_case and CAPITAL.
In the case of Java, enums can also be used to achieve something similar but they will contain a lot of java boilerplate.
There are also language-specific naming conventions involved like:
Java and Typescript prefer camelCase
Python and SQL prefer snake_case
For Unit test cases
My aim is not so much about reducing the lines of code. Tests are usually small. (In case your tests are huge and complex then you must have written a bad code)
I prefer to keep the end of each method the same. Like:
I use Mockito so I skip the first line. The start of the function then is with all stub actions.
The last 3 lines are usually similar.
A variable expected: expected value
A variable actual: calls the function/method
I find that for most tasks it is easier to make changes to expected and actual variables rather than put everything into assertions. The assertion is always clean.
An alternative to the above assertion is to write like below which I find to be messy.
Previous: Flat is better than nested
Next: Avoid creating god classes and long methods #NotEnoughChunks
Index: Tips on writing Clean Code