Аннотируйте эти вещи — серия о качестве внешнего кода (1)

Цель аннотации:

• Улучшить читаемость кода и, следовательно, его ремонтопригодность

Принципы аннотации:

• Не добавлять комментарии, если в этом нет необходимости (как можно короче)

• Сколь угодно долго

Согласно принципу комментариев, мы должны судить о том, является ли комментарий «необходимым», исходя из того, «может ли он помочь читателям лучше читать и понимать код».

Хорошие заметки включают в себя:

• Помогите читателям лучше понять логику и структуру кода, например:

init: function() {
  // 获取配置信息
  const config = getConfig();
  
  // 获取用户信息
  const userInfo = getUserInfo();
  
  // 根据配置和用户信息，进行初始化
  doInit(config, userInfo);
  
  // 如果存在自定义配置时的特殊逻辑
  if (config.custom) {
    ...
  }
}

• Специальные или трудные для понимания пояснения, такие как:

/** 
 * parseInt was the reason my code was slow. 
 * Bitshifting the String to coerce it to a 
 * Number made it a lot faster. 
 */
const val = inputValue >> 0;

• Примечания к специальным меткам: метки со специальными значениями, такие как TODO, FIXME и т. д.
  

• Примечания к файлу: некоторые правила требуют, чтобы в начале файла была написана примечание фиксированного формата, например, автор, соглашение и другая информация.
  

• Комментарии класса документации: часть соглашений использует комментарии класса документации (например, стиль jsdoc) для API, классов, функций и т. д.

• Следуйте унифицированным спецификациям стиля, таким как определенные пробелы и пустые строки, чтобы обеспечить удобочитаемость самих комментариев.
  

К плохим комментариям относятся:

• Комментарии бесполезны для чтения кода: как и в первом примере в этой статье, вы можете использовать четкие имена и логику для самоаннотирования кода без комментариев.

• Не соответствует единой спецификации стиля: такой как длина однострочного комментария, пробелы, пустые строки, например:

// bad 单行注释过长，不易阅读，应写成多行
// parseInt was the reason my code was slow.Bitshifting the String to coerce it to Number made it a lot faster.
const val = inputValue >> 0;

// good
/** 
 * parseInt was the reason my code was slow. 
 * Bitshifting the String to coerce it to a 
 * Number made it a lot faster. 
 */
const val = inputValue >> 0;

• Эмоциональные ноты: такие как жалобы, дискриминация, забавные вещи и т. д. (вы встаете на колени, когда вас находят)

Спецификация аннотации

Понимать цель и принципы аннотаций, а также разрабатывать и соблюдать спецификацию аннотаций, чтобы обеспечить удобочитаемость и согласованность аннотаций.

Гарантия на инструмент

Например, используйте ESLint, чтобы обеспечить согласованность стиля аннотаций, и используйте Sonar, чтобы проверить скорость аннотирования проекта.

04 Протокол аннотаций

// bad
const active = true; // is current tab

// good
// is current tab
const active = true;

// bad
function getType() {  
  console.log('fetching type...');  
  // set the default type to 'no type'
  const type = this.type || 'no type';  
  return type;
}
  
// good
function getType() {  
  console.log('fetching type...');  
  
  // set the default type to 'no type'
  const type = this.type || 'no type';  
  return type;
}

// good
// 注释行上面是一个块的顶部时不需要空行
function getType() {  
  // set the default type to 'no type'
  const type = this.type || 'no type';					
  return type;
}

// bad
// make() returns a new element
// based on the passed in tag name
function make(tag) {
  // ...

  return element;
}

// good
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {
  // ...

  return element;
}

// bad
//is current tab
const active = true;

// good
// is current tab
const active = true;

// bad
/**
 *make() returns a new element
 *based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element;
}

// good
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element;
}

class Calculator extends Abacus {
  constructor() {
	super();

	// FIXME: shouldn’t use a global here
	total = 0;

	// TODO: total should be configurable by an options param
	this.total = 0;
  }
}

/**
 * Book类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author) {
  this.title=title;
  this.author=author;
}

Book.prototype={
  /**
   * 获取书本的标题
   * @returns {string|*}
   */
  getTitle:function(){
	return this.title;
  },

  /**
   * 设置书本的页数
   * @param pageNum {number} 页数
   */
  setPageNum:function(pageNum){
	this.pageNum=pageNum;
  }
};

Sonar: проверьте скорость аннотации проекта

Sonar — это платформа непрерывной интеграции кода, которая может статически сканировать код для получения данных о скорости аннотирования проекта.

Уровень комментариев отражает долю закомментированных строк в общем количестве строк кода. Слишком низкий уровень комментариев не является хорошим, но невозможно слепо следовать высокому уровню комментариев.

Кроме того, как и в Eslint, в Sonar также есть некоторые настраиваемые правила стиля аннотаций.

06 Постскриптум