LINUX.ORG.RU
Форум — Development  

Комментарии в коде для заливки на Google Code

 , , , ,


0

2

Есть ли какие-нибудь удобные стандарты комментариев и организации файлов в проекте?
Слышал, что есть точные стандарты CamelCase'а для названий переменных, есть ли стандарты для комментариев?
Суть такова: начал делать небольшой проектик, контроль версий ещё не использую. Сейчас создал проект на гуглокоде, выбрал лицензию GNU GPLv2.
Форматированием пусть занимается IDE (кроме избранных мест, где я расставляю табуляции руками). А вот с организацией файлов и комментариев - беда. Совсем не знаю, есть ли стандарты.
Должен ли я добавлять в начале каждого файла текст лицензии комментарием? Допустимы ли комментарии на русском языке? (кроме того, что это вызовет трудности с кодировками, если стянуть файлы из под венды, проверено)
Нормально ли закомментировать участок кода так: 

		/*someFunct(3);
		otherFunction(someVar);
		variable = 17;
		variable++;
		Map m = new Map(18, 18, variable);*/
вместо: 
		/*
		 * someFunct(3);
		 * otherFunction(someVar);
		 * variable = 17;
		 * variable++;
		 * Map m = new Map(18, 18, variable);
		 */

Нужно ли вылизывать код, чтобы он был красивым (имею ввиду комментарии/форматирование) перед заливкой на гуглокод?

★★★★★
← REPL в Common Lisp и в других ЯП
XOR для float. Оригинальное решение →

Нормально ли закомментировать участок кода так:

нормально — вообще не закомментировать, а удалить или переписать

theNamelessOne ★★★★★
()

где я расставляю табуляции руками)

символов табуляции в исходном коде не должно быть.

(кроме того, что это вызовет трудности с кодировками, если стянуть файлы из под венды, проверено)

ни разу проблем не было. Держи файлы в utf8 кодировке

JFreeM ★★★☆
()
Ответ на: комментарий от CYB3R

Как же без них? Пробелами?

разумеется. Впрочем на счет tab vs spaces былв куча холиваров, В java coding conventions например, четко сказано, что должны быть только пробелы. Какаие стандарты в вашем язык я не знаю.

Файлы в UTF-8, у вендоюзеров проблемы, ибо CP-1251.

еще раз говорю. Сырцы джавского проекта, кодировка файлов utf8, ide - eclipse, netbeans, intekkij idea - никаких проблем с кириллицей. Блокнотом открывать не пробовал, впрочем.

JFreeM ★★★☆
()

GNU GPLv2

Любим швабодку?

кроме того, что это вызовет трудности с кодировками, если стянуть файлы из под венды, проверено

Пускай открывают нормальными редакторами, это не проблема с кодировкой. Там только с переносами могут быть проблемы.

комментарии

Удалить лучше.

tensai_cirno ★★★★★
()
Ответ на: комментарий от CYB3R

Это не дело. Либо сделай сразу как надо, либо удали, а иначе через N единиц времени у тебя весь код будет в таких «комментариях»

theNamelessOne ★★★★★
()

Если в удаляемом коде какие-то очень важные хитрые наработки, то они один йух останутся в истрории vcs. Так что не сто́ит засирать код бесполезными комментами.

anonymous
()
Ответ на: комментарий от anonymous

Вот поэтому я и решил использовать контроль версий!

CYB3R ★★★★★
() автор топика
Ответ на: комментарий от Hoodoo

Так почти так оно и есть.

CYB3R ★★★★★
() автор топика

Должен ли я добавлять в начале каждого файла текст лицензии комментарием?

http://www.gnu.org/licenses/gpl-howto.html

есть ли стандарты для комментариев?

Их есть: doxygen, javadoc, gtk-doc...

Нормально ли закомментировать участок кода так

За комментирование кода надо пороть.

ratvier ★★
()

А вот с организацией файлов и комментариев

точно также есть множество подходов, как и для форматирования кода. Вот например на вопрос

Нормально ли закомментировать участок кода так:

есть люди которые отвечают 

#if 0
	someFunct(3);
	otherFunction(someVar);
	variable = 17;
	variable++;
	Map m = new Map(18, 18, variable);
#endif

выбрал лицензию GNU GPLv2

Будь разумным человеком и пиши в тексте 'GPLv2 or (at your option) any later version'

Должен ли я добавлять в начале каждого файла текст лицензии комментарием?

Давайте посмотрим что написано в http://www.gnu.org/licenses/old-licenses/gpl-2.0.html по поводу применения лицензии:

It is safest to attach them to the start of each source file

То есть GPL рекомендует добавлять соответствующее уведомление о лицензии в начало каждого файла. Это не обязательно, но рекомендовано.

Допустимы ли комментарии на русском языке?

Проблема русских комментариев не в кодировке (в конце концов пишешь в начале файла «/* -*- coding: utf-8 -*- */ и дальше читатель предупреждён чистым ASCII о том какая кодировка), а в том, что представители сообщества знают, обычно, только pidgin english. То есть они не смогут прочитать твой русский. Если есть уверенность, что твоя работа никогда не понадобится корейцам, индусам или американцам, то можешь использовать русский.

> Нужно ли вылизывать код, чтобы он был красивым (имею ввиду комментарии/форматирование) перед заливкой на гуглокод?

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

стандарты … организации файлов в проекте?

Есть набор широко распространённых практик. Например класть сорцы в каталог ./src/, класть документацию в ./doc/, класть INSTALL, REDME и ChangeLog в корень проекта, но точно также множество проектов складывают всё в одну кучу в корне и не комплексуют по этому поводу.

стандарты комментариев …?

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

kim-roader ★★
()
Ответ на: комментарий от JFreeM

В java coding conventions например, четко сказано, что должны быть только пробелы. Какаие стандарты в вашем язык я не знаю.

Кожу я на Java, но Eclipse при автоформатировании упорно ставит символы табуляции. Думаю и так сойдёт. Люблю табуляцию.

И ещё вопрос: создавать коммиты на каждый чих не моветон? Делаю коммиты, конечно, не в том случае, если значение переменной изменил, но довольно часто, с незначительными изменениями. Ведь незначительные изменения легко можно описать в commit message.

CYB3R ★★★★★
() автор топика
Ответ на: комментарий от CYB3R

Кожу я на Java, но Eclipse при автоформатировании упорно ставит символы табуляции.

настроить не пробовали?)

И ещё вопрос: создавать коммиты на каждый чих не моветон? Делаю коммиты, конечно, не в том случае, если значение переменной изменил, но довольно часто, с незначительными изменениями. Ведь незначительные изменения легко можно описать в commit message.

ит депендс, коммитить надо не реже раза в день, а насколько часто - не критично

JFreeM ★★★☆
()
Ответ на: комментарий от JFreeM

коммитить надо не реже раза в день

А если я решил отдохнуть от проекта недельку, почитать книжку? Или появились неотложные дела? Кожу я чисто для себя, для саморазвития, так сказать. Дедлайна для меня не существует.

CYB3R ★★★★★
() автор топика
Ответ на: комментарий от JFreeM

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

коммит должен быть по-возможности атомарным и разумным (чтобы было понятно к чему он, а не переменную i сменил на j) и ограниченным одним модулем

желательно чтобы один коммит фиксил/апал одну фичу

и да, каменты так пишутся лучше и понятнее, много коммитов - это не плохо, а совсем даже хорошо, гораздо хуже когда некий «быстрокодер» вываливает 1,5 тысячи строк в 20 модулях под конец рабочего дня и подписывает «implemented new kernel features» и все ему шлют тонны факов и «сосо»

shty ★★★★★
()
Ответ на: комментарий от CYB3R

Кожу я на Java, но Eclipse при автоформатировании упорно ставит символы табуляции.

может уже долезть до настроек и поставить галочку напротив replace tabs with spaces?

shty ★★★★★
()
Ответ на: комментарий от JFreeM

Это хорошая тема для холивара))

/me ушлёпок, который применяет табы.

ssvda ★
()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.
← REPL в Common Lisp и в других ЯП
Development
XOR для float. Оригинальное решение →