Clean Code - Deepstash
Clean Code

Coding Harry's Key Ideas from Clean Code
by Robert C. Martin

Ideas, facts & insights covering these topics:

10 ideas

·

83 reads

2

Explore the World's Best Ideas

Join today and uncover 100+ curated journeys from 50+ topics. Unlock access to our mobile app with extensive features.

Write Better Comments Part 1.

Write Better Comments Part 1.

Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.

Comments are not like Schindler's List. They are not "pure good." Indeed, comments are, at best, a necessary evil. If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much, perhaps not at all.

4

14 reads

Good Comments

Good Comments

Some comments are necessary or beneficial. We'll look at a few that I consider worthy of the bits they consume. Keep in mind, however, that the only truly good comment is the comment you found a way not to write.

4

8 reads

Legal Comments

Legal Comments

Sometimes our corporate coding standards force us to write certain comments for legal reasons. For example, copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.

Here, for example, is the standard comment header that we put at the beginning of every source file in FitNesse. I am happy to say that our IDE hides this comment from acting as clutter by automatically collapsing it.

/ Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.

5

8 reads

Informative Comments (1)

Informative Comments (1)

It is sometimes useful to provide basic information with a comment. For example, consider this comment that explains the return value of an abstract method:

/ Returns an instance of the Responder being tested. protected abstract Responder responderInstance ();

A comment like this can sometimes be useful, but it is better to use the name of the function to convey the information where possible. For example, in this case the comment could be made redundant by renaming the function: responderBeingTested.

Here's a case that's a bit better:

// format matched kk:mm:ss EBE, MMM dd, yyyy

4

6 reads

Informative Comments (2)

Informative Comments (2)

Pattern timeMatcher = Pattern. compile (

"'|d*: 11d*: 1 1d* Ww*, Ww* Nd*, lId* n) :

In this case the comment lets us know that the regular expression is intended to match a time and date that were formatted with the SimpleDateFormat. format function using the specified format string. Still, it might have been better, and clearer, if this code had been moved to a special class that converted the formats of dates and times. Then the comment would likely have been superfluous.

4

8 reads

TODO Comments (1)

TODO Comments (1)

TODOS are jobs that the programmer thinks should be done, but for some reason can't do at the moment. It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem. It might be a request for someone else to think of a better name or a reminder to make a change that is dependent on a planned event. Whatever else a TODO might be, it is not an excuse to leave bad code in the system.

4

6 reads

TODO Comments (2)

TODO Comments (2)

Nowadays, most good IDEs provide special gestures and features to locate all the TODO comments, so it's not likely that they will get lost. Still, you don't want your code to be littered with TODOs. So scan through them regularly and eliminate the ones you can.

5

5 reads

Bad Comments

Bad Comments

Most comments fall into this category. Usually they are crutches or excuses for poor code or justifications for insufficient decisions, amounting to little more than the programmer talking to himself.

5

9 reads

Misleading Comments

Misleading Comments

Sometimes, with all the best intentions, a programmer makes a statement in his comments that isn't precise enough to be accurate. Consider for another moment the badly redundant but also subtly misleading comment we saw in Listing 4-1.

Did you discover how the comment was misleading? The method does not return when this.closed becomes true. It returns if this.closed is true; otherwise, it waits for a blind time-out and then throws an exception if this closed is still not true.

4

6 reads

Misleading Comments (2)

Misleading Comments (2)

This subtle bit of misinformation, couched in a comment that is harder to read than the body of the code, could cause another programmer to blithely call this function in the expectation that it will return as soon as this .closed becomes true. That poor programmer would then find himself in a debugging session trying to figure out why his code executed so slowly.

4

13 reads

IDEAS CURATED BY

codingharry

Aspiring full stack developer

CURATOR'S NOTE

Learning to write clean and descriptive comments inside your code requires skill, but you should avoid it! Learn how important (or not) are comments within your code through the first part of the clean code book

Curious about different takes? Check out our Clean Code Summary book page to explore multiple unique summaries written by Deepstash users.

Coding Harry's ideas are part of this journey:

How To Become A Digital Nomad

Learn more about books with this collection

How to build a network while working remotely

How to work remotely

How to manage finances while working remotely

Related collections

Different Perspectives Curated by Others from Clean Code

Curious about different takes? Check out our book page to explore multiple unique summaries written by Deepstash curators:

Discover Key Ideas from Books on Similar Topics

Read & Learn

20x Faster

without
deepstash

with
deepstash

with

deepstash

Personalized microlearning

100+ Learning Journeys

Access to 200,000+ ideas

Access to the mobile app

Unlimited idea saving

Unlimited history

Unlimited listening to ideas

Downloading & offline access

Supercharge your mind with one idea per day

Enter your email and spend 1 minute every day to learn something new.

Email

I agree to receive email updates