Clean Code


20 najlepszych cytatów z książki Roberta Marina Clean Code (Pearson Education, 2008 r.)


I. Najlepsze cytaty dotyczące nazewnictwa w kodzie

1. Use Intention-Revealing Names. It is easy to say that names should reveal intent. What we want to impress upon you is that we are serious about this. Choosing good names takes time but saves more than it takes. So take care with your names and change them when you find better ones. Everyone who reads your code (including you) will be happier if you do. Don’t be afraid to make a name long. A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment. Choosing descriptive names will clarify the design of the module in your mind and help you to improve it.

2. The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent. int d; // elapsed time in days The name d reveals nothing. It does not evoke a sense of elapsed time, nor of days. Weshould choose a name that specifies what is being measured and the unit of that measurement:

Choosing names that reveal intent can make it much easier to understand and change code. What is the purpose of this code?

Why is it hard to tell what this code is doing?

3. Do not refer to a grouping of accounts as an accountList unless it’s actually a List. The word “list” means something specific to programmers. If the container holding the accounts is not actually a List , it may lead to false conclusions. So accountGroup or bunchOfAccounts or just plain accounts would be better. Use exact names.

4. Because you can’t use the same name to refer to two different things in the same scope, you might be tempted to change one name in an arbitrary way. It is not sufficient to add number series or noise words, even though the compiler is satisfied. If names must be different, then they should also mean something different.

5. Noise words are redundant. The word variable should never appear in a variable name. The word table should never appear in a table name. How is NameString better than Name? Would a Name ever be a floating point number? If so, it breaks an earlier rule about disinformation. Imagine finding one class named Customer and another named CustomerObject . What should you understand as the distinction?

How are the programmers in this project supposed to know which of these functions to call?

6. The length of a name should correspond to the size of its scope. Shorter scope do not need so much information to understand of variable purpose. Shorter names are generally better than longer ones, so long as they are clear. Add no more context to a name than is necessary.

7. Do not use Hungarian notation. It was considered to be pretty important back in the Windows C API. The compiler did not check types in those days, so the programmers needed a crutch to help them remember the types. In modern languages we have much richer type systems, and the compilers remember and enforce the types. So nowadays HN and other forms of type encoding are simply impediments.

  • Classess and function should be small so that people can usually see the point of declaration of each variable they’re using.
  • Editing environments have advanced such that they detect a type error long before you can run a compile!
  • They make it harder to change the name or type of a variable, function, or class.
  • They make it harder to read the code.
  • And they create the possibility that the encoding system will mislead the reader.

8. Classes and objects should have noun or noun phrase names (like Customer , WikiPage , Account , and AddressParser). Avoid words like Manager , Processor , Data , or Info in the name of a class. A class name should not be a verb.

9. Methods should have verb or verb phrase names (like postPayment , deletePage , or save) . Accessors, mutators, and predicates should be named for their value and prefixed with get , set , and is.

10. Pick One Word per Concept. Pick one word for one abstract concept and stick with it. For instance, it’s confusing to have fetch , retrieve, and get as equivalent methods of different classes. Avoid using the same word for two purposes. Using the same term for two different ideas is essentially a pun.

11. Add Meaningful Context. There are a few names which are meaningful in and of themselves—most are not. Instead, you need to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces. When all else fails, then prefixing the name may be necessary as a last resort. Imagine that you have variables named firstName , lastName , street , houseNumber , city , state , and zipcode . Taken together it’s pretty clear that they form an address. But what if you just saw the state variable being used alone in a method? Would you automatically infer that it was part of an address? You can add context by using prefixes: addrFirstName , addrLastName , addrState , and so on. At least readers will understand that these variables are part of a larger structure. Of course, a better solution is to create a class named Address . Then, even the compiler knowsthat the variables belong to a bigger concept.


II. Najlepsze cytaty dotyczące funkcji


12. The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that. What this experience has taught me, through long trial and error, is that functions should be very small.

13. Functions should do one thing. They should do it well. They should do it only. The following advice has appeared in one form or another for 30 years or more.

14. The statements within our function are all at the same level of abstraction. Mixing levels of abstraction within a function is always confusing. Readers may not be able to tell whether a particular expression is an essential concept or a detail. Worse,

15. Reading Code from Top to Bottom: The Stepdown Rule. We want the code to read like a top-down narrative. We want every function to be followed by those at the next level of abstraction so that we can read the program, descending one level of abstraction at a time as we read down the list of functions.

16. Avoid flag arguments. Flag arguments are ugly. Passing a boolean into a function is a truly terrible practice. It immediately complicating function and proclaiming that this function does more than one thing. It does one thing if the flag is true and another if the flag is false! Usually we should have split the function into two.

17. Decrease number of arguments. When a function seems to need more than two or three arguments, it is likely that some of those arguments ought to be wrapped into a class of their own.

18. Functions should not have side effects - side effects are lies. Your function promises to do one thing, but it also does other hidden things.

19. Don’t comment bad code—rewrite it. The proper use of comments is to compensate for our failure to express ourself in code. Comments are usually lies - they are not maintained with as much care as code.

Or this?

20. Throw out Dead Function. Methods that are never called should be discarded. Keeping dead code around is wasteful.Don’t be afraid

Przedstawione wyżej cytaty mogą stanowić wskazówki jak podnieść jakość kodu. By dowiedzieć się więcej zachęcam do sięgnięcia po książke z której cytaty pochodzą.

TAGS: DMA, FreeRTOS, Unit testy