Loose Java coding conventions

What about this article?

It is a coding standard created for in-house development. I myself have been afflicted by some unintended coding conventions created by other companies in the past, and I have loosened it considerably.

Should I follow this agreement?

There may be an idea that it is a convention and should be obeyed. But I don't like that kind of straightforward idea. If the purpose is to follow the coding standards, it will be overwhelming. So, in the extreme, you don't have to follow this coding convention. Then why write? That's because you don't have to hesitate if you have some rules. If you are confident, ignore this coding convention (or modify it). Please refer to this coding standard when you are wondering what to do.

Usage Guide

★ </ font>: Important. This agreement should not be violated. If there is a rationale to violate, you should change the coding conventions. However, you should be prepared to refactor all sources as your coding conventions change. ◆ </ font>: Important. If you are confident that you are violating, but this is better! This is a good time to consider changing your coding conventions. ● </ font>: Recommended. If you are not particular about it, follow it for the time being.

Naming convention

Common

● </ font> Basic idea

Basically, follow the Google Java Style Guide (unofficial Japanese translation).

★ </ font> Think carefully.

Proper naming means a concise and clear definition of what "it" is. This is program design.

If you have trouble naming

  • Program design is not concise and clear
  • I don't understand the specifications
  • Legacy costs are too high

There may be a problem such as. (= Problem can be detected)

If the naming is texto, this alert will not work and the program design will collapse more and more.

Let's give a name that is just right, "There is only this!"

★ </ font> In principle, it must be in English. Japanese, romaji, and mysterious codes are NG.

The mysterious code (screen ID, etc.) is NG because it is not clear at first glance what it refers to. Romaji is simply hard to read, so NG. In Japanese, it is troublesome to press the full-width / half-width key every time, so it is NG.

Good example


public class Employee {
    public String name;
    private Decimal monthlyIncome;
}

bad example


public class Class002 {
    public String namae;
private Decimal monthly income;
}

◆ </ font> Do not use abbreviations other than the most common ones.

Because it takes time to decipher the abbreviation. On the contrary, it takes time to make an abbreviation.

Object menuFlg; // NG:'Flg'Is FLaG? FLaGment?
String employeeNm; // NG:'Nm'Is Name? NuMber?
SystemParameterDAO dao; // OK:'DAO'Is common to point to a DataAccessObject
DBConnection dbConnection; // OK:'DB'Commonly refers to DataBase

If the name is long enough to make an uncommon abbreviation, you should suspect that the program design is not appropriate. Also, variables with a very narrow scope may be easier to see if they are abbreviations, so in that case it is OK.

Good example


public class Corporation {
    private List<Employee> employees;
    public List<String> getEmployeesNameList() {
        List<String> result = new ArrayList();
        employees.forEach(e -> result.add(e.getName());
        return result;
    }
}

bad example


public class Org {
    private List<String> corpEmpNmLst;
    public String getcorpEmpNmLst() {
        return corpEmpNmLst;
    }
}

As an aside, I once died in a project with a mysterious convention of romaji + vowel abbreviation (GakuseiBango-> GKSIBNG).

Package class name

● </ font> Base class name

Basically, it follows the class name. However, I would like you to avoid using <SubClassName> Base in a straightforward manner because of derived classes. The Developer superclass should be ʻEmployee, not DeveloperBase, and that superclass should be Person`.

Variable / constant / method name

◆ </ font> Variable name

For boolean values, name it so that the meaning of true / false is clear, such as ʻis-, has-. Boolean -Flag` is categorically rejected.

◆ </ font> method name

For the method that returns the boolean value, refer to the variable name mentioned above.

Coding style

★ </ font> Appearance

It's up to the code formatter to write indents, {}, multiple statements on one line, and so on. It's a waste of resources to be distracted by that while coding.

◆ </ font> Nest

Deepening the nest is usually something wrong. As a guide, if you have more than 3 layers, you should reconsider.

Good example


public List<String> fizzBuzzList(List<Integer> themes) {
    List<String> result = new ArrayList<>();

    for(Integer theme: themes) {
        result.add(fizzBuzz(theme));
    }
    return result;
}

private String fizzBuzz(Integer theme) {
    Map<Integer, String> rule = new LinkedHashMap<>();
    rule.put(30, "FizzBuzzFizz");
    rule.put(15, "FizzBuzz");
    rule.put(5, "Buzz");
    rule.put(3, "Fizz");
    for(Integer ruleKey: rule.keySet()) {
        if(0 == theme % ruleKey) return rule.get(ruleKey);
    }
    return theme.toString();
}

bad example


public List<String> fizzBuzzList(List<Integer> themes) {
    List<String> result = new ArrayList<>();

    for(Integer theme: themes) {
        if(0 == theme % 3) {
            if(0 == theme % 5) {
                if(0 == theme % 2) {
                    result.add("FizzBuzzFizz"); 
                } else {
                    result.add("FizzBuzz"); 
            } else {
                result.add("Fizz");
            }
        } else if(0 == theme % 5) {
            result.add("Buzz");
        } else {
            result.add(theme.toString());
        }
    }
    return result;
}

◆ </ font> Double negation is incomprehensible

Humans are not smart enough to understand the double negation. Negation is a very costly process for humans.

Good example


public Boolean isActive(Boolean visible, Boolean enable) {
    return visible && enable;
}

bad example


public Boolean isNotInactive(Boolean invisible, Boolean notDisenable) {
    return !invisible && notDisenable;
}

◆ </ font> Logical operator Do not dance

Use one logical operator per statement, if possible, and at most three. No further logical operations are possible for humans.

bad example


Boolean isTooBad = (!(arg1.equals('1') && arg2 == 0) || arg0 > 30) ^ arg3.canRead(); 

◆ </ font> Destroyer magic numbers

The magic number here has a broad meaning and includes a character string. I do not understand the meaning, I can not repair it, I do not know the range of influence, so it will be a triple pain, so please destroy it as soon as you find it. Of course, unless the meaning is clear, such as 0! = List.size ().

Good example


public Decimal getPrise(Item selectedItem, Campaign campaign) {
    return selectedItem.prise() * campaign.discountRate() * Constants.TAX_RATE;
}

bad example


public Decimal getPrise(Item selectedItem, Boolean campaign) {
    if(compaign) {
        return selectedItem.prise() * 0.8 * 1.08;
    } else {
        return selectedItem.prise() * 1.0 * 1.08;
    }
}

comment

Javadoc Attach as much as possible to classes and members. In that case, use Javadoc tags appropriately. In particular, @ param, @ return, @ throws, and @ deprecated are required as needed. On the contrary, @ author and @ since are not required separately. It will not be maintained properly anyway. It is a relic of the time when there was no version control system.

◆ </ font> Unnecessary comments are destroyed

There are too many unnecessary comments in the world. Please destroy the following comments as soon as you find them.

  • Commented out and left the source before renovation just in case
  • Comments indicating the repair range (start / end position), repair date, repairer, etc.
  • Description of very simple processing // Substitute 10 for variable a
  • Process description linked to the specification // This process represents the table yy on the nn page of the specification xxx

In particular, when "comment out just in case" and "comment on repair position" exist, I feel that the impact range investigation man-hours, correction man-hours, and bug occurrence rate will increase 1.5 to 4.0 times compared to the case where they do not exist.

● </ font> Welcome comments

Comments that say "what was the purpose of writing this process (Why)" or "other methods can do the same, but why not (Why not)" are welcome. From this comment, you can predict the expected result, and if the execution result does not meet the expected result, you can detect that it is a bug.

Good example


void createCurry(RetortCurry retortCurry) {
      //Warm the curry hot (Commentary:"Hot"It is important to make it, and you can imagine that you need to change the number of seconds depending on the power of the range and the capacity of the curry)
      Microwave.execute(retortCurry, 180);
      //Put it on a plate in consideration of its appearance (Explanation: The order of putting it on a plate is"Looks good"のためにこの順にしていることがわかる。Looks goodを無視すれば順番は崩してもよい)
      return new Dish().add(rice).add(retortCurry).add(fukujinzuke);
}

bad example


void createCurry(RetortCurry retortCurry) {
      //Put the curry in the microwave, set it for 180 seconds, and run it (Explanation: I don't know the purpose, so I don't know if the number of seconds needs to be changed even if the power of the microwave or the capacity of the curry changes)
      Microwave.execute(retortCurry, 180);
      //Place rice, curry, and Fukujinzuke on a plate (Explanation: I don't know what the purpose is, so I can't change the order)
      return new Dish().add(rice).add(retortCurry).add(fukujinzuke);
}