What defines a clean code?

Asked

Viewed 1,168 times

33

I saw this term being employed several times, many people and companies want their codes to be "clean"... I also saw the book Clean Code Agile Software Practical Skills.

But I wanted to know what defines a code to be cleaned or not? What points are evaluated once knowledge and mastery over a particular language can influence the evaluation of who is reading.

In the question "Writing easy-to-maintain, readable code?" we have some examples of a code that is apparently well written, but the mastery of language is what makes a lot of difference when interpreting it.

So focusing well on the question, what points are evaluated? What is the importance and weight of each of these points within the evaluation?

I would mainly like the references to study a little more in depth, and not limited to a paradigm (ex: Object Orientation) but in a general context.

software-engineering encoding-style

  • I’m still thinking about the tags, I don’t know if this one is more appropriate. I answered because I think you can have an objective answer. Of course, the previous ones were not helping varied from something very specific that gives room for subjectivity to the explicit definition that is opinion. I avoided to deny them but in my understanding they flee from what was asked. The blame for the opinions does not seem to be the question.

  • @bigown I’m also thinking about the tag, it’s hard to define and also don’t know how could be the name for a new tag...

  • The answer to this question is either subjective and therefore not useful, or is succinct and therefore not useful, or yields a book. Read the Uncle Bob book you quoted (464 pages in the original English version) and you will find what you are looking for. Here in the OS you will not find.

  • 1

    @Caffé unfortunately I do not have time for such extensive reading, so I thought I could find something more summarized of the professionals who deal with it

  • Keep reading the answers and see that unfortunately you will not find something summed up and at the same time useful for you. But I can suggest a philosophy to get you in the way: the code needs to tell a story, it needs to be read and understood as if it were in very clear Portuguese and telling a story that makes a lot of sense to the business the software serves - without relying on comments.

  • @Caffé wants only the definition, not a treatise on the subject. The quoted book is a treatise (and for being detailed, debatable) on the subject. A summary of the principles can be useful. Of course the utility is limited, but the answers do not need to close the subject, they do not need to be theses. In fact, in Research Methods and Techniques we learned this well. If abstracts were useless, scientists should not publish them. I deliberately did not cite sources because when it details it is usually biased favoring one technique over another with no basis at all.

  • @bigown I don’t understand what part of my comment you refer to, since I didn’t say that the book is indisputable, I didn’t say that summaries are useless, I didn’t say that the answers need to close the subject or that they should be theses. Also, what you said about scientists and summaries didn’t make any sense to me. I just tried to guide the questioner. And for now it’s quite easy to frame all the answers here: no use to the questioner or the OS visitor.

  • And I didn’t say that you said the book is indisputable, I’m just giving you relevant information. At the other point quoting you: "succinct and therefore not useful". I know it didn’t make sense to you but it must have made for those who know how the scientific community works, that succinct information is useful also for the evolution of science. Imagine in a more informal environment like ours how useful it can be. There are those who disagree with you about the usefulness of the question and the answers (at least one), and there are those who agree.

  • @bigown "I know it didn’t make sense to you but must have done for who knows how the scientific community works" is a naive stratagem. As we are on the page of a specific question, not useful succinctly refers, of course, to the characteristic of the answers to this specific question; and not to the evolution of science, nor to our informal model of the OS.

  • 4

    Open the book you mentioned in the first chapter you will see. Pay close attention to the first illustration, which says what it is the only valid quality metric for source code ;)

  • 1

    @Renan I’ll take a look at this chapter then :D

Show 6 more comments

2 answers

22


There is no formal definition and I doubt that one day it will exist (it is symptomatic that there is no entry in Wikipedia). It is subjective. Whenever someone says what it is, be suspicious. But of course some observations can be made independent of opinion. It is obvious that they are vague and will not help much to define clearly what the term is, but they will not make biased presumptions either.

  • The implementation flow of the application is easily understandable, no matter in which paradigm, (do not understand flow only as the imperative flow).
  • The various objects (nothing to do with OOP) have clearly defined relationship and it is easy to perceive them.
  • The role and responsibility of each application participant (classes, functions, variables, etc.) are clear, possibly with a well-chosen name.

At the moment I can not remember anything else that is not specific and too subjective to be applied as a general way of understanding the subject.

So the code needs:

  • Be easy to understand by whom I had never seen him before.
  • Makes it possible maintenance no major shocks.
  • Works correctly.

Of course, the reader of the code is expected to be an able developer, who understands well the language where it is written and understands the fundamentals of computing. Unless a code is written for didactic purposes it is not an obligation of clean code to explain in any way its functioning to laymen (even those who are paid as developers, this exists, and much).

Here we can begin to define some more specific things that help to meet these three requirements highlighted above:

  • Code units shall be short and have only one responsibility.
  • The "public" parts (the API) should be clear (obvious, no surprises) and concise (makes the minimum necessary).
  • Data structures and algorithms should work as expected.
  • The code shall be easily verifiable.
  • Codes should be organized and expressive (concisely indicates their intention)

In addition it is probably going beyond the basic definition and begins to enter the subjective field.

I even used a very recent font to write this reply. Nor am I going to quote it because my text is sufficiently different and the original induces the dictatorship of the monoparadigm that the PA so well denied. Paradigms are not magical, they do not solve problems. They are tools that can be more or less suitable.

The first chapter of the book is available as article. As the book deepens it suggests certain things that are debatable. The book is not bad, everyone should read it, but who is not sufficiently prepared ends up buying indiscriminately some techniques, at least doubtful.

In the question that has been quoted by the AP I do a quick analysis of the book and another that deals with similar subject.

Just an addendum to avoid giving the false impression that 100% of the written code should be cleared. Of course this would be ideal but there are certain domains in conjunction with certain requirements that conflict with the concept of clean code. It may be rare, not applicable in certain types of project, but there are situations like that. As in everything, you should know when to pursue an ideal and when to be pragmatic and solve the problem in the most appropriate way.

  • On your addendum, I would just suggest that the most appropriate form is always the cleanest. It’s best to always write clean code (even if it’s subjective, do your best). This possibility will not always exist, but to think that you can afford to decide when or not to do it can foster the horrible quality of what we have seen out there. At first difficulty the developer will abandon their practices and return to the hack-n-Slash.

  • An example of where no clean code could be found was in the Openssl implementation. They were able to identify which was the private key according to low-frequency waves when transporting variables between registers, then the code had to be purposely dirty to give a red herring so that the attacker can’t figure out which is the primary key

7

There are several factors that define clean code, some that I consider important:

  • Each function/method has a single well-defined responsibility, carrying out a single action.

  • The use of variable names, classes and descriptive functions without ambiguity.

  • Indentation of the code.

Browser other questions tagged software-engineering encoding-style

You are not signed in. Login or sign up in order to post.