Комментирование конвенций

Question

Я хочу знать, каковы некоторые рекомендации для комментирования? Я кодирую в Java для класса. Я хочу иметь читаемый код. В другом вопросе мне сказали, «как» комментарии должны быть зарезервированы для сложных разделов кода. Мне сказали, что мои комментарии к коду не содержат никакой информации. Комментарии не только для читателей. Они также напоминают писателю об их первоначальном намерении и помогают сопоставлять символы группировки.

Я новичок в Java и Stackoverflow. Почему я одержим? Я думал, что этот сайт был разработан, чтобы позволить программистам помогать друг другу. Я чувствую себя как цель, потому что у меня есть вопрос с голосованием -3. Мы здесь, чтобы помочь новым программистам или здесь, чтобы гордиться своими сундуками за чужой счет?

Answer 1

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

Самая важная вещь, которую вы должны знать о комментировании на Java, - это Javadocing. Это специальный тип комментариев, который можно анализировать и использовать в IDE (например, Eclipse и Netbeans), чтобы упростить процесс кодирования. Комментарии Javadoc начинаются с / ** и заканчиваются * / Это похоже на обычный многострочный комментарий, но с двумя звездочками в первом.

Вы помещаете комментарии Javadoc в начале классов, методов или переменных экземпляра, чтобы описать, что они делают. Существуют стандартные способы форматирования данных в комментарии, которые являются тегами. Некоторые общие теги - @author и @version. Вы можете увидеть некоторые предложения Sun по написанию комментариев на Javadoc здесь: http://java.sun.com/j2se/javadoc/writingdoccomments/

После этого мне нравится использовать однострочные комментарии (двойная косая черта //) для описания моей логики. Если мне нужно более одной строки, я просто буду использовать несколько однострочных комментариев. Преимущество этого метода заключается в том, что если вам необходимо позднее закомментировать большие фрагменты текста, вы можете использовать обычный многострочный комментарий / * * /, не беспокоясь о проблеме вложенных комментариев.

Я надеюсь, что это поможет вам получить общее представление о том, как использовать комментарии в Java. Мой совет отчасти является результатом работы ассистента преподавателя, которую я выполняю на вводном курсе в университете, а частично - работы в промышленности. Другие с другим фоном могут иметь больше предложений.

Answer 2

Я бы следовал рекомендациям по переполнению стека, упомянутым в следующих постах:

• Когда не комментировать код
• Условные обозначения для функций / классов Комментарии
• Каков ваш персональный подход к комментированию?

Answer 3

Большие вещи, которые я комментирую:

• Название алгоритма. Например, если я пишу алгоритм для вычисления пикселей в линии между двумя точками, я оставлю комментарий, в котором говорится, что это реализация алгоритма Брезенхема.

• Если я отправляю жестко закодированное, магическое, значение в функцию (например, true, null, 42 и т. Д.), Я бы прокомментировал, что представляет это значение.

• Если я реализую структуру данных, мне нравится комментировать, говоря, какие операции она предназначена для оптимизации. Например, если бы я реализовывал очередь (правда, вы бы использовали каркас для очереди), я бы сказал что-то вроде структуры данных FIFO с O (1) вставкой, удалением и размером.

• Я пытаюсь оставить комментарий в начале каждого класса и метода, чье имя не раскрывает всех тонкостей реализации. Однако я часто не решаюсь делать это вообще. Чаще всего, когда возникает такая проблема, рефакторинг более уместен.

Answer 4

Во-первых, читаемый код и читаемые комментарии - это две совершенно разные вещи. Читаемый код - это код, использующий хорошие переменные, методы, имена классов и т. Д.

Читаемые комментарии - это вопрос личного вкуса. Некоторые люди любят комментарии, чтобы следовать грамматическим правилам, которые будут использоваться для написания книги, в то время как другие не заботятся о грамматических вещах.

Answer 5

Комментарии предназначены для читателя кода. Конечно, читатель кода также может быть писателем. Но так или иначе, вы хотите рассказать читателю то, что они не могут легко увидеть из кода. Чрезмерные или избыточные комментарии просто не синхронизируются с реальным кодом.

Answer 6

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

При этом руководящие указания в отношении комментариев должны исходить из политики вашего рабочего места или, в вашем случае, от вашего учителя. Если ваш учитель говорит, что вам не нужны комментарии в определенном месте, то вам это не нужно.

Когда вы закончите с классом, не стесняйтесь комментировать, как хотите.