Learn more about computerscience with this collection
Understanding machine learning models
Improving data analysis and decision-making
How Google uses logic in machine learning
A misuse of comments is to provide information that should have been in the code. An example is when someone names variables badly and then tries to add comments describing them:
# A dictionary of families who live in each city
mydict = {
"Midtown": ["Powell", "Bran"],
"Norcross": ["Mont"]
}
def a(dict):
# For each city
for p in dict:
# If there are no families in the city
if not mydict[p]:
# Print it
print("None.")
This script could have been made simpler by using obvious names for variables, functions and collections.
13
25 reads
MORE IDEAS ON THIS
Your comments should be D.R.Y. The acronym stands for the programming maxim “Don’t Repeat Yourself.” This means that your code should have little to no redundancy. You don’t need to comment a piece of code that sufficiently explains itself. For example:
return a # Returns a
14
24 reads
The most infamous comment in the Unix source code is “You are not expected to understand this,” which appeared before some hairy context-switching code. It turned out that Dennis Ritchie and co-author Ken Thompson didn’t understand it themselves and later had to rewrite it.
Warning readers ...
13
17 reads
Most programmers use code that they find online. Including a reference to the source enables future readers to get the full context, such as:
13
16 reads
"Programs must be written for people to read and only incidentally for machines to execute."
13
55 reads
It’s a good idea to comment code that someone else might consider unneeded or redundant, such as this code:
final Object value = (new JSONTokener(jsonString)).nextValue();
// Note that JSONTokener.nextValue() may return
// a value equals() to nu...
13
32 reads
Comments should be added not just when initially writing code but also when modifying it, especially fixing bugs. Consider this comment:
// NOTE: At least in Firefox 2, if the user drags outside of the browser window,
// mouse-move (and even mouse-down) events will ...
12
17 reads
All programs should be commented in such a manner as to easily describe (in English) the purpose of the code and any algorithms used to accomplish the purpose. A developer should be able to utilize a previously written program (or function) without ever having to look at the code, simply by readi...
13
62 reads
Sometimes it’s necessary to check in code even though it has known limitations. While it can be tempting not to share known deficiencies in one’s code, it is better to make these explicit, such as with a TODO comment:
// TODO: We are making the decimal separator be a period,
13
12 reads
Read & Learn
20x Faster
without
deepstash
with
deepstash
with
deepstash
Access to 200,000+ ideas
—
Access to the mobile app
—
Unlimited idea saving & library
—
—
Unlimited history
—
—
Unlimited listening to ideas
—
—
Downloading & offline access
—
—
Personalized recommendations
—
—
Supercharge your mind with one idea per day
Enter your email and spend 1 minute every day to learn something new.
I agree to receive email updates