In this article, I will describe a very important issue, which is reading other people's code, but at the same time, I will also provide tips on how to write your own code so that someone else can understand it. When working with the git tool, each piece of code has information about the author, changes to the code and when the changes were made. Therefore, "evading" your own code is impossible, saying, it's not my code that won't work.
Preface
I will only focus on the readability of the code, which is immediately noticeable during the first code review. Additionally, I will describe such an important issue as Definition of Done, i.e. the issue of determining when the code that has been written is considered finished.
In this article, I will not delve into such code elements as:
– application architecture,
– providing functionality via API,
– application modules/layers.
I will deal with such code elements as:
– naming convention,
– order of elements in a class,
– self-describing code,
– design patterns,
– SOLID and DRY good practices.
We read the source code like a well-written book
“Code written in any programming language should read like a good book. A person reading a book would not want to be bored with exact copies of book fragments placed in many places in the same book (DRY - Don't Repeat Yourself). It would be difficult to read a book that has mixed chapters, the action is not coherent and one has the impression that the author probably didn't know what he was writing (SOLID).” – article "Why should Java code be SOLID and DRY?„.
It is true that just knowing the basics of Java does not mean that we will write readable, correct and nice code. Just like knowing Polish, not everyone can write books, we also have various literary genres, e.g. novel, drama.
Definition of Done – when is my code complete?
Let's start with the Definition of Done - when is my code complete? A book has a beginning and an end, consists of chapters, and at some point it is published so that readers can become familiar with the work of a given author. In the case of books, the process of creating and publishing is systematized. It's the same with the source code, but not everyone realizes that knowledge of Java is just the beginning (more in the article Is Java alone enough?), and the software development process is a team effort.
Going back to the Definition of Done, when writing source code you need to determine what you mean by "I've finished writing my code, now someone can use it." Why even Definition of Done in an article about how to write readable code? Not everyone understands when the code is finished. I will explain using the example of business requirements for making foreign transfers - more about business requirements in the article I only want to write code, I'm not interested in business requirements!.
According to the junior programmer, the code responsible for foreign transfers is finished when he manages to transfer funds from one test account to another test account - of course we do not do tests on production like mBank. According to an experienced programmer, it is finished when it has unit tests and is SOLID and DRY. However, for a person submitting a business requirement, finished code is one that has been placed on a test server, tested by manual testers and is consistent with the business requirement.
Self-describing code
Coming back to readable code that we write ourselves or when we read someone else's code. As always, the stick has two ends. Many times I have seen my colleagues tearing their hair out while reading someone else's code, often asking aloud the questions "how is it possible", "who wrote it anyway", "after all, it has no chance of working", " Where is Heniek, I'm going to him! It is very easy to check who is the author of a given piece of code, just use the command git-blame . Bearing in mind what I wrote, you should write your own code so that when your code is read, a team of Terminators won't be sent after you.
Naming convention
The naming convention is a very important element, I recommend reading the official Oracle documentation Code Conventions for the Java TM Programming Language describing the naming conventions for the Java language - the documentation can also be downloaded as PDF.
The order of elements in a class
At some stage, when you have a lot of experience in coding in Java, browsing through classes does not look like you start from the first line and move on to the next one and the next one. When viewing a class, we check in which variables the class stores its state, how it is constructed, and then what methods it provides, and then we wonder what we can use it for. We assume that the variables are at the very beginning of the class body, below them are the constructors, methods with business logic, and at the very end the "helper methods" getter/setter and toString.
Now imagine a situation in which a programmer looks through the fiftieth class of a given day and each time he encounters a different order of elements in the class. He loses his rhythm, cannot concentrate, and thus his efficiency decreases. It's like the chapters of a book mentioned at the beginning, which has mixed chapters.
Self-describing code
The code we write should beself-describing, i.e. when we see the name of a method and/or variable we immediately know what it is for and we do not have to wonder what the author had in mind. If we use comments for a method and/or a variable, it means that we do not know what a given piece of code represents. The only allowable comment for code is Javadoc, which is used to later generate documentation for our code. Every Framework has a Javadoc, e.g. Springframework API Doc .
What does self-describing code look like? Here's an example of a good and bad naming convention.
// nazwa klasy nie opisuje jej przeznaczenia i funkcji
public class Main {
// metoda 'calculate' nie wiemy, co dokładnie robi
// musimy zagłębiać się w jej kod
public double calculate(int a, int b) {
return a / b;
}
}
// nazwa klasy opisuje jej przeznaczenia i funkcji
public class Calculator {
// metoda 'division' od razu informuje o tym, co będzie robić
public double division(int a, int b) {
return a / b;
}
}
Design Patterns
At the beginning, I would like to point out that in the everyday work of a Junior Java Developer, he rarely has the opportunity to introduce a design pattern into an existing system. Why am I writing about this at the beginning? I would like to emphasize that a junior Java programmer should focus more on SOLID and DRY good practices, and then expand their skills to include design patterns. I will also add that there is no tool that detects design patterns in code.
Additionally, the design patterns that are presented in many tutorials are detached from reality. What do I mean by that? In a real system, design patterns are not highlighted in any particular way in the code as they are in tutorials. In the existing system, we will not find classes such as: MenuComposite (Composite Pattern), InProgressState (State Pattern). We will rather encounter theMenu class, which is a composite (Composite Pattern), theJob class in combination with theStep class will represent a state pattern (State Pattern). .
Good practices SOLID and DRY
As I wrote above, a junior developer should focus on good practices when writing code, rather than forcefully using design patterns. I wrote more about SOLID and DRY in the article Why should Java code be SOLID and DRY?
English 
Polski