Форматування і стиль коду

Найпоширеніший стиль форматування програмного коду в середовищі Java програмістів це Sun Java Code Conventions. Біда в тому що останній раз той документ переглядався 1999 року.

Існують і альтернативи. Наприклад рекомендації Стіва Макконнелла в його книзі "Code Complete". Також деякі поради можна взяти із "Effective Java" Джошуа Блоха.

Я вирішив скласти до купи вищезгадані поради та запропонувати наступний варіант організації файлу програмного коду.

/* Created: September 8, 2008. Author: Maksym Shostak. 
Copyright notice text... */
package org.somecompany;

import edu.umd.cs.findbugs.annotations.*;


/** One-line summary of class goal (responsibility).
.......................................................
Description of class including:
1. Responsibilities.
2. Design patterns used.
3. How to use this class (for clients). Is this class a data
 (value) object or a computation one?
4. Inheritance instructions. Do or do not subclass it?
5. Thread safety and serrialization. Error handling, etc.
@author Maksym Shostak.
@version 1.2008. */
public class AnotherClass{

/* Methods to Create and Destroy Objects ************
  Description of approaches used. */
/** Constructor summary. */
public AnotherClass(){
}

/* Public Member Functions *************************/

/** One-line summary of member function.
.....................................................
Description of function
Describe function's exceptions and return values */
public void doSomething(
@Nullable int in_Parameter1, // description
final SomeStatuses ch_MethodStatus // description 
) throws Exception{

///
///
///

}

/* Member Functions Common to All Objects **********/
@Override @OverrideMustInvoke
public String toString(){
    ///
  }


/* Protected, Package-pr., Private Member Functions*/
private static void initialize(){
///
}


/* Data Members (Public...Private) *****************/
public static final int MAX_COUNT = 10;
private int m_Counter = 0;

/* Inner Structures Definitions ********************/
public enum SomeStatuses{
Success,
Failure
}

private class InnerClass{
}


/* Initialization Blocks ***************************/
static{
initialize();
}


/* main() Function  ********************************/
public static void main( String in_Arguments[] ){
///
}

}

Основні відмінності від рекомендаці Sun це:

• Порядок розташування методів та полів класу обумовлений принципом приховування інформації (деталей реалізації). Згідно з яким клієнт класу повинен цікавитися тільки зовнішнім інтерфейсом класу.


• Префікси полів класу, параметрів методів мають таке значення: m_ - поле класу (member), in_ - вхідний параметер (input), out_ - вихідний параметер (output), ch_ - змінюваний параметер (change), ret_ - локальна зміння, що її вертає метод (return).
  
  
• Розташування вкупі методів, які відповідають за створення та знищення об'єкту, а також методів загальних для всіх класів.


• Розташування анотацій, тощо.

Альтернативним порядком розташування методів в класі є розташування за алфавітом.

Отже не забуваймо, що програмний код читається набагато частіше ніж пишеться. Конвенції іменування та форматування програмного коду можуть суттєво впливати на продуктивність програмістів та на здатність розуміти програму, що підтверджено дослідженнями. Але іноді проходять десятиріччя, поки кращі практики програмування розповсюджуються достатньо широко.

А які Ваші конвенції іменування? Чи зустрічали Ви пропозиції щодо організації коду у файлах тестів?

І на останок трохи гумору з фільму Комп'ютерщики