preface

Have you read a book called Clean Code?

When I first heard it, I didn’t want to read it. Hearing this again, I thought: How can code be clean? I’d like to see how it’s done.

I read the book with the intention of testing my heart, and got a head full of bad code. My god! This code I look like a word also don’t understand, fortunately there are words, still can comfort me this code hit disorderly heart, so read down.

There are 17 chapters in this book about clean code, including meaningful naming, functions, comments, formatting, error handling, boundaries, and more. If you’re interested, you can check it out. I just glanced at it, because I couldn’t understand some of it either. Especially when some code exists outside of the computer, it’s like I don’t recognize it anymore, it’s strange. Forgive me for my ignorance, alas.

Still, chapter 4 of the book impressed me with its code neatness about “comments.” Why? It was the comments that refreshed my mind, soul-struck me a little, convinced me, and drove me to write this article.

1. Be attracted to comments

Here are the first two paragraphs of the “notes” chapter, posted specifically because that’s what I was attracted to. I hope it gives you a little inspiration.

I wonder how you feel after reading the above two paragraphs?

My feeling is that if your code is good enough, you don’t need too many comments. At best, comments can prove bad code.

Well, I’m really looking for a face covering emoji right now. At the same time, I quickly recalled a comment in my mind: from the initial know “comment” such a magical thing when the joy, to step by step fall into the “comment” claws, so that now looking at the full screen of code, do not write some comments feel empty……

Take it back and continue. The author begins by saying something like this:

  • The proper use of comments is to compensate for our failure to express intent in code
  • If you find yourself needing to write comments, think again about whether there is a way to turn around and express them in code
  • Comments lie, code changes and evolves, but comments don’t always follow
  • The code is the only accurate source of information

Notice the use of the word “failure”. You can’t find the right way to express yourself, so you have to use annotations, which is not something to celebrate. Of course, this does not mean that the author completely dismisses the value of comments; it is the programmer’s responsibility to keep the code maintainable, relevant, and precise. But authors tend to focus their efforts on writing clean code, either by making sure they don’t have to write comments, or by reducing the number of comments.

Second, good comments

Some comments are necessary, and the author lists some that are worth writing.

  • The company code specification requires the writing of comments relating to the law
  • Notes that provide basic information
  • Interpretation of intent
  • Interpretation: To translate the meaning of an obscure parameter or return value into some readable form
  • Warning: A comment used to warn other programmers of a consequence
  • TODO comment: Is something that programmers think they should do, but for some reason haven’t done yet
  • Magnify: a note that amplifies the importance of something that seems unreasonable
  • Javadoc in the public API

Still, the authors reiterate that the only really good comments are the ones you try not to write. It shows how much the author hates comments, how much he hates bad code, and how much he wants clean code. You can taste it in detail.

Bad comments

True to code cleanliness fanatics, the authors devote more space to bad comments.

  • Mumbling: Adding comments because the process requires it is pointless
  • Redundant comments: provide no more information than the code itself, or even the time it takes to read the code
  • Misleading comments: Write comments that are not precise enough to mislead the reader
  • Canonical annotation: The rule that every function should have Javadoc or every variable should be commented is silly
  • Logging comments: Every time you edit code, a comment is added at the beginning of the module and should be removed altogether
  • Gibberish comments: gibberish comments that turn into a bunch of lies when the code changes
  • Don’t use comments when you can use functions or variables: Refactor the code to remove comments
  • Location marking: Marking a particular location in source code is often irrational and trivial
  • Note after parentheses: If you find yourself wanting to mark the closing parentheses, you should shorten the function instead
  • Attribution and attribution: Source control is the best place to attribute this information
  • Commented out code: Commented out code piles up like the dregs at the bottom of a wine bottle
  • HTML comments: HTML tags in source code comments are a nuisance
  • Non-local information: If you must write a comment, make sure it describes the code closest to it
  • Too much information: Don’t add interesting historical topics or irrelevant details to your notes
  • Non-obvious relationships: The connection between comments and the code they describe should be obvious
  • Function headers: Short functions don’t need much description, so choosing a good function is good for writing function header comments

In short: Replace the urge to create crap with the determination to clean up code. You’ll find yourself a better, happier programmer.

summary

The author takes the “comments” out and says so much, but ultimately comes back to the code itself.

So how do you write clean code? There’s no point in trying to write clean code if you don’t understand what clean code means. If you understand the cost of bad code, you know that taking the time to keep your code clean is about survival as well as efficiency. Try to leave the camp cleaner than you came! Finally, I will post a piece from the book that shocked me. I hope it can guide you gradually towards the path of code neatness.