hlx Jun 15 2012 at 00:59

Оформление кода

5 min

65K

Programming*

+11

109

Comments 109

UFO just landed and posted this here

novoselov Jun 15 2012 at 07:53

"_" не исключение, для приватных полей следует использовать this.variable синтаксис.

Meroving Jun 15 2012 at 18:06

это неправда. Во-первых, не путайте официальный гайдлайн с правилами хорошего тона. Устоявшихся традиций даже не две, а скорее три: с this, с underscore (_) и c m_. Последняя менее распространена, но ею, например, пользуется Рихтер.
Во-вторых, даже в официальном гайдлайне ничего не сказано о правилах именования приавтных полей. Пруф: msdn.microsoft.com/en-us/library/ms229012.aspx The naming guidelines for fields apply to static public and protected fields. You should not define public or protected instance fields.

novoselov Jun 20 2012 at 07:35

SA1309: FieldNamesMustNotBeginWithUnderscore.
By default, StyleCop disallows the use of underscores, m_, etc., to mark local class fields, in favor of the ‘this.’ prefix.

Официальный гайдлайн не все читают, справедливости ради StyleCop тоже не все используют. Раньше сам писал m_, потом _, потом this. В Microsoft так-то бардак в исходных кодах привычное дело, так что проще положиться на инструмент который проверит и подскажет, чем на бумажный гайдлайн.

Teacher Jun 15 2012 at 08:23

Угу, и имена методов с большой буквы в C#. Для и для имен булевых переменных, лично мне нравятся вопросительные предложения. Т.е. имя переменной не «done», а «isDone». Как то логичнее выглядит.

VolCh Jun 15 2012 at 13:33

job.isDone — вопросительное предложение?

-1

Teacher Jun 15 2012 at 13:38

Во-первых, я говорил про переменные, а вы привели пример свойства/поля.
Во-вторых, да я считаю, что при чтении
if (job.IsDone)
лучше, чем
if (job.Done)
В-третьих, каждая команда вырабатывает свои соглашения, если вам больше нравится без Is, то это ваше право, просто надо всем придерживаться этого стиля и все…

VolCh Jun 15 2012 at 14:42

В некоторых языках используется название именно «переменные объекта/класса», свойств/полей там нет. Но вообще я спросил, имея в виду, что в случае имени переменной/свойства/поля, то есть jobIsDone или job.isDone.isDone (сам такую форму предпочитаю) это утверждение, подразумевающее наличии какого-то объекта (не в смысле ООП, а в смысле существительного) могущее быть ложным или истинным, но не вопрос.

Cancel Jun 15 2012 at 16:23

Немного в офтопик уйду: нравится, как это в ruby сделано, прямо в названии метода знак вопроса, исключительно хорошо.

akzhan Jun 15 2012 at 22:55

и тут же замечу, что однозначно фигово в Ruby то, что это касается только методов-геттеров.

1.9.3-p194 :001 > @done? = false

SyntaxError: (irb):1: syntax error, unexpected '='

@done? = false

 ^

 from /usr/local/rvm/rubies/ruby-1.9.3-p194/bin/irb:16:in `'

jakobz Jun 15 2012 at 16:43

Бесит "_" у приватных полей в C#.

sdevalex Jun 15 2012 at 01:11

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

edogs Jun 15 2012 at 01:18

Не знаю как можно не следовать общему стилю

Очень просто.
Когда проект большой, нужно сделать что-то небольшое, а времени знакомиться со всеми гайдлайнами проекта нет, то… вполне можно ляпнуть getJuneStat вместсо принятого getJunStat, при чем если рядом нет кода в котором написано getJunStat, то Вы просто не заметите, что Вы белая ворона:)

hlx Jun 15 2012 at 01:19

Вы говорите верно, но иногда встречается код, из-за которого готов бросить программирование :)
А вообще, с книгой, ссылка на которую есть в конце топика, должен ознакомится каждый, особенно начинающий программист.

kulinich Jun 15 2012 at 13:04

ИМХО С этой книгой обязан познакомиться каждый не начинающий программист. По крайней мере 1 — 2 года опыта программирования должно быть, хотя бы для того, чтобы понимать что в ней написано.

VolCh Jun 15 2012 at 13:34

Угу, ознакомиться начинающему может быть просто вредно, если он начнёт следовать принципам не понимая зачем.

UFO just landed and posted this here

VolCh Jun 15 2012 at 08:08

откровенно плохое имя метода чаще всего является главным свидетельством его неудачной реализации

arturich Jun 15 2012 at 01:15

«obj1, obj2» как говориться — «нет худшей причины назвать переменную $c, чем та, что $a и $b уже заняты»

TheHorse Jun 15 2012 at 02:32

Ну на самом деле, многие так делают, и все правильно делают. Например, олимпиадное программирование, когда времени очень мало…

EuroElessar Jun 15 2012 at 02:44

В олимпиадном программировании это не так критично на самом деле :) Много времени за компьютером тратится на обдумывание того — как писать, имена переменных по сравнению с этим тратят очень мало времени.
Ну и не стоит забывать, что IDE вполне сносно автодополняют имена переменных/методов/классов, а ими (IDE) на олимпиадах пользоваться не запрещено.

EuroElessar Jun 15 2012 at 02:52

И, конечно же, не стоит забывать, что ваш код потом еще, возможно, придется читать сокоманднику, а он точно не обрадуется одно-двухсимвольным названиям переменных, если названия взяты наобум (w для ширины, h для высоты — логично, а вот «a» и «b» для того же — уже сложнее гораздо читать). В таком случае все сэкономленные секунды на написание коротких имен будут многократно съедены тем временем, которое ваш товарищ потратит на понимание кода — а вы ведь в это время, скорее всего, будете писать уже следующую задачу.

arturich Jun 15 2012 at 08:49

У всех есть скрипты, которые «просто должны работать и не важно что внутри», вот только внутри обычно такая жесть творится, что автор через месяц уже ничего не прочтет. Поэтому я обдумываю каждое название в коде — бывает долго, но иначе потом будет хуже.

А вообще, если вспомнить Дяду Боба, то в книге «Чистый код» он много и дотошно все моменты разбирает и объясняет что и почему.

TheHorse Jun 15 2012 at 10:57

Не критично, но юзают. А я и не говорил что время именно на кодирование уходит, пишут a, b, c, d… в том числе чтоб и не задумываться над названием. Ну и все-же кодируется так все быстрее, и аутокомплит тому не перечит.

Чтение сокомандником, происходит редко, и при наличии автора, который показывает и рассказывает.

Ну в общем, ваши аргументы, приняты частично). И как факт, таки многие так делают, и иногда все правильно делают.

TheHorse Jun 15 2012 at 11:15

Ну и помимо олимпиадного, нормальный пример для a, b, c:

procedure swap(var a : integer, var b : integer);
var c : integer;
begin
     c := a;
     a := b;
     b := c;
end;

Что явно лучше чем FirstVariableForSwaping / swapVar1 / tempVar и кучи всего другого.

leotsarev Jun 15 2012 at 13:25

arg1, arg2, temp

TheHorse Jun 15 2012 at 13:52

Мне кажется, что это не лучше чем a, b, c.

arg1, arg2 — не информативно, и так понятно что процедура принимает первый аргумент, второй аргумент…

temp — возможно и лучше, но если функция занимает 3 строки, и есть гарантия от самих небес что функция меняться не будет (как эта), то лучше не задумываться а писать что удобней.

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

VolCh Jun 15 2012 at 14:33

С a, b и c могут возникнуть ненужные ассоциации. Например две функции рядом triangle_square(a, b, c) и swap(a, b). Если первая понятна любому, изучавшему геометрию в школе (и английский :) ), то этого же любого вторая может заставить полезть в реализацию. чтобы посмотреть, а что же там со сторонами треугольника происходит, хотя никакого отношения ни к треугльнику, ни геометрии вообще она не имеет. Правда arg1 и arg2 неудачные названия, я бы взял var1 и var2, подчеркнув, что нужно указывать именно переменные, а не произвольные выражения.

TheShock Jun 15 2012 at 14:36

Есть ещё вариант — назвать «left» и «right» или «first» и «second»

TheHorse Jun 15 2012 at 14:42

swap — основы основ, название как бы намекает, что там за аргументы).
a, b, c — часто используются в высшей математике, алгебре и прочих весомых науках.

VolCh Jun 15 2012 at 14:55

Вот и я про то, может возникнуть диссонанс между swap и её аргументами a и b. Вроде swap чисто техническое название, а a и b — научные.

TheHorse Jun 15 2012 at 15:16

Так хотелось найти пример, но боюсь что boost, .Net, Qt напилили что-то похожее на value1, value2 для таких функций((.

a,b — все-же скорей инженерные, нежели научные. Наука кишит всякими тау, гамма… Впрочем и а, b к сожалению тоже.

Ну ладно, буду делать как все, но аргумент в сторону сильных ассоциаций к a,b — не принимаю). Не верю в существование программистов, которые при виде swap(a, b) подумают про стороны треугольников.

UFO just landed and posted this here

Mrrl Jun 18 2012 at 09:58

Непонятно. Что такое «треугольный квадрат»? Я такого не только не знаю, но и представить себе не могу. Или имелось в виду TriangleArea?

VolCh Jun 18 2012 at 10:58

Имелось, но словарь выдал на слово «площадь» перевод «square», а не «area». А представьте от меня ещё требуют комментарии иногда на английском писать :(

UFO just landed and posted this here

edogs Jun 15 2012 at 01:22

Всё же не все правила абсолютны.

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

Если они большие, то можно и по ссылке. Пару мегабайт данных на фига пихать в функцию «напрямую»?
Если в функции 7 входных параметров, все из которых используются и сама функция небольшая, то переопределение может занять больше места/времени чем использование их как рабочих и привести след. разработчика в задумчивость.
Фактически это обязательно только в публичном методе. Приватный метод вполне имеет право полагаться на проверку этих данных перед ним. Иначе в цепочке вызовов может оказаться такой копипаст проверок, что жуть.

sic Jun 15 2012 at 02:46

Бывают еще и константные ссылки, которые как раз в большинстве случаев предпочтительны. И тогда их не удастся использовать как рабочие переменные.

HotWaterMusic Jun 15 2012 at 01:29

Спрашивал месяц назад по этому вопросу того самого Джона Кармака в Твиттере. Он же увлекается всяким таким. Кармак сказал, что по вопросам читабельности кода самое лучшее — вот это.
Ссылок на PDF на английском если что хватает, а лично мне книга понравилась, легко читается легко и сразу есть практическая польза. Code Complete безусловно шире по охвату тем и сравнивать их не стоит, но вдруг кто-то и эту книжку возьмет на вооружение.

creage Jun 15 2012 at 01:30

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

edogs Jun 15 2012 at 01:36

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

Согласитесь, читать такой код:

Код красивый
function()
{
$a = 1;
$b = 2;
$c = 3;
$sql = '
SELECT
*
FROM
tbl
WHERE
a = 1';
}

Код компактный
function(){
$a = 1;
$b = 2; $c = 3;

$sql = 'SELECT * FROM tbl
WHERE a = 1';
}

Более приятно, чем

Приятно может быть и первый, но хорошим компромиссом для такой ситуации имхо было бы все-таки

Код компромисный

function(){
$a = 1; $b = 2; $c = 3;
$sql = 'SELECT * FROM tbl WHERE a = 1';
}

Потому что первый тип кода приводит к тому, что частенько приходится пролистывать страницы. Код должен быть разумно компактен. Особенно учитывая моду последних лет, когда 4:3 мониторы скукожили до 16:10, а потом и до 16:9… или вообще сумашедшие 21:9 habrahabr.ru/post/145276/

DevMan Jun 15 2012 at 01:53

Метод не должен быть слишком большим (не более 100)

Не более чего? Строк/экранов/*байт/грамм? :)

GrigoryPerepechko Jun 15 2012 at 02:01

А разве не очевидно?

-1

DevMan Jun 15 2012 at 02:22

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

-1

GrigoryPerepechko Jun 15 2012 at 10:47

Знаете, если человек подумает про 100 экранов или 100 байт, ему лучше не продолжать программировать. Ему даже code complete не поможет. Всё таки у программистов должен быть мозг

DevMan Jun 15 2012 at 11:07

Да ладно. Вы реально весь такой правильный и никогда не делаете ошибок?

GrigoryPerepechko Jun 15 2012 at 15:37

При чем тут то делаю я ошибки или нет?
Я просто уверен что большинство тут люди с хорошими мозгами, и однозначно поняли о какой еденице измерения шла речь.
Метод размером 100 строк. Очевидно же.

Какие к черту байты, экраны? Зачем вы бред несете? Вам приятно ощущать себя дурачком?

Это серьёзный IT ресурс а не ясельная группа. Да, хабр сгавнивается с годами, все меньше серьёзных постов, но ведь это не повод устраивать смешнявочки из за недописок. Если вы нашли однозначную ошибку в статье — ну писните автору в ЛС. Зачем разводить детский сад?

TheHorse Jun 15 2012 at 15:48

Инженерия и наука требуют точных высказываний, которые не дают шанса термину «неоднозначность».

Да, было очевидно что там про строки, но оно просто сильно ~~бесило~~ выделялось и потому автор критики не мог пройти мимо.

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

DevMan Jun 15 2012 at 16:04

Про очевидность я вам ответил выше.
Для вас очевидно (должно быть у вас есть мозг). Для меня очевидно (знаком с software metrics). A для кого-то начинающего может быть очевидно, что метод должен содержать не более 100 операций.

В итоге, не нравится мой комментарий — есть минус для него, есть минус в карму.
Выпустите пар на них и продолжайте читать сей серьёзный IT ресурс, вместо рассуждений на тему мозга у программистов.

resurection Jun 15 2012 at 17:45

Конечно все догодались, но для этого пришлось напрячь мозг на 0.5 секунд. Ирония в том, что это в статье про перфикционизм и про прекрасно офрмленный, легко-читабельный код. Если бы эта надпись была в любой другой статье — никто бы и не обратил внимание.

resurection Jun 15 2012 at 02:39

Тут тоже всё очевидно:

function(){
  $a = 1;
$b = 2; $c = 3; $sql = 'SELECT * FROM tbl
WHERE a = 1'; return $this->my_sql->q($sql);
}

Что тут не очевидного?

DevMan Jun 15 2012 at 02:44

Все очевидно. Только за такое форматирование кода хочется человека как минимум обозвать. Как минимум — редиской.

resurection Jun 15 2012 at 02:45

"(не более 100)" — за это тоже.

hlx Jun 15 2012 at 02:49

за троллинг — тоже. Я же исправил.

-1

TheHorse Jun 15 2012 at 16:17

Мне что-то не очевидно зачем там $a, $b, $c. И что такое метод q?

TheHorse Jun 15 2012 at 16:18

И как потом вызвать эту функцию? О чем пример?

hlx Jun 15 2012 at 02:11

Спасибо, исправил

f0b0s Jun 15 2012 at 02:44

Очень напоминает пересказ одной из глав «Совершенного кода»

f0b0s Jun 15 2012 at 02:49

Ах, автор об этом упомянул. Я воспользовался правилом «The Wadsworth Constant» и сразу начал читать со второй трети статьи.

anitspam Jun 15 2012 at 02:52

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

dxArtem Jun 15 2012 at 02:53

Если реч идет о PHP, то я всех, у себя в компании, пропогандирую PEAR coding standards.
В основном из-за того, что Drupal взял за базу эти правила и чуть-чуть изменил их под себя.
Drupal coding standards

А это, по моему скромному мнение уже слишком.

Код из статьи

function()
{
    $a = 1;
    $b = 2;
    $c = 3;
    $sql = '
        SELECT
            *
        FROM
            tbl
        WHERE
            a = 1';
}

Я бы писал так

function foo() {
    $a = 1;
    $b = 2;
    $c = 3;

    $sql = 'SELECT *
              FROM tbl
            INNER JOIN tratata
              ON zozo.zozo = zaza
            WHERE 
             a = 1 OR
             z = 1000';
}

Ну или как edogs в комментарии.

-1

hlx Jun 15 2012 at 03:05

оформление SQL кода, с новой строки (как у меня), или придерживаюсь всех отступов — как у вас, уже пожеланию. Главное что бы был читаем SQL (beautiful query). Различия незначительны, лишь в количестве действий при наборе — у вас отступов больше :)

а по поводу скобок и пустых строк — это, как описано в топике — строго по гайдлайнам компании.

alekciy Jun 15 2012 at 04:02

Ничуть не слишком. Это удобно читать и камитить. Пример:

$sql = '
	SELECT
		  i.e_id
		, iv.iv_id		AS id
		, iv.value
		, iv.ep_id		AS element_property_id
	FROM
		' . $this->schema . '.item AS i
	LEFT JOIN
		' . $this->schema . '.item_value AS iv USING (i_id)
	WHERE
		i.i_id = '. $this->db->getSqlInt($item['id']) . '
';

Весь «скелет» запроса виден по SELECT...FROM...LEFT JOIN...WHERE. Из какой таблицы выборка, что выбираем, с чем джоиним, по каким условиям. Запятые в начале для камитов. Если завтра потребуется добавить новое поле, то в дифе мы увидим ", iv.new", т.е. затронута будет одна строка, а не две как в случае если поля разделять запятыми в конце строки.

VolCh Jun 15 2012 at 08:16

LEFT JOIN я бы сдвинул ещё, всё таки он относится к FROM, а не является самостоятельным элементом SELECT.

А вообще, когда выражение простое вроде «SELECT * FROM table», то при виде его разбитым на 4 строки возникает неоднозначная реакция.

alekciy Jun 15 2012 at 16:26

В JOIN, как и в FROM, находится имя таблицы, поэтому он вровень с FROM. Ведь по сути, работаем мы уже не с таблицей указанной во FROM, а таблицей полученной объединением. Поэтому в SELECT у нас имена полей, а в FROM...JOIN таблица.

Какой бы простой код не использовался, он должен соответствовать стилю кодирования. Это сильно облегчает чтение кода, а бОльшую часть времени на живом проекте мы все же читаем, а не пишем код. Разбиение на несколько строк очень полезно оказывается для дифов. При однострочной записи изменение любой чисти запроса приводит к включению в диф камита всего запроса, разделенный же на строки запрос в дифе дает только измененные строки. Крайне полезно при командной разработке, особенно при отслеживании камитов других разработчиков. Но и работая в одиночку подход показывает себя очень удобным. Читаемость должна находится на первом месте. Многословность форматирования легко может фикситься через минификацию/обфускацию на этапе сборке проекта. В контексте php это сборка в phar файл(ы).

VolCh Jun 15 2012 at 16:40

Ну я сматриваю (а иногда и пишу) FROM… JOIN… ON… как FROM (… JOIN… ON ...), то есть имея ввиду как раз, что «аргументом» FROM является как раз «виртуальная» таблица, а состоит она из одной или объединения двух или более — не суть. Ваш вариант мне напоминает запись типа

$var
=
  2
+
  2

а я предпочитаю

$var
  =
    2
    +
    2

alekciy Jun 15 2012 at 17:28

Ну тут уж кому как удобно/какой стиль кодирования принят в проекте. Я лично за первый, т.к. идет разделение на уровне форматирования на оператор, идущий без отбивки, и его операнды, идущие с отбивкой слева. В твоем же случае два оператора, = и +, отбиты по разному. Хотя логика понятна «сложение 'внутри' присвоения».

VolCh Jun 15 2012 at 16:50

>Читаемость должна находится на первом месте.

Согласен, вот только представления о ней у каждого свои :)

>Многословность форматирования легко может фикситься через минификацию/обфускацию на этапе сборке проекта. В контексте php это сборка в phar файл(ы).

Обычно это не нуждается в фиксе. А сборка php-проекта, по-моему, очень редкий зверь. Я так его наблюдал только когда пробовал HAML прикрутить к PHP из спортивного интереса.

alekciy Jun 15 2012 at 17:32

Редкий, просто потому что народ на это тупо забивает/не думает. Это как быдлокодинг. Но сбор проекта в один файл дает неплохой прирост. Поэтому я лично считаю этот аспект на столько важным, что хочу включить сборку в единый phar файл в своем проекте.

VolCh Jun 15 2012 at 18:14

Информации о плюсах мало, а привычные сценарии разработки, разворачивания, обновления и поддержки (читай — правка кода на сервере :) ) ломает.

А вообще я больше не о phar (тут-то понятно, без сборки никуда), а вещах вроде «инлайна» инклудов, минимизации html, css и js, то есть препроцессинге и компиляции не в рантайме.

Shedal Jun 15 2012 at 04:18

А зачем у вас перед FROM отступ? По логике ведь, эта строка не менее (а то и более) первостепенна, чем INNER JOIN.

dxArtem Jun 15 2012 at 04:38

Сложно писсать код в камментариях, размер отступов в textarea отличается на отображении, не заметил :)

Shedal Jun 15 2012 at 04:41

Кстати, я в WHERE отступы делаю по той же самой логике, вот так:

SELECT *
FROM tbl
INNER JOIN tratata
  ON zozo.zozo = zaza
WHERE a = 1
  AND z = 1000

В случае с AND условия получаются ещё и выстроены на одном уровне.

dxArtem Jun 15 2012 at 04:45

Да, это разумнее. Я на самом деле так же пишу, спеша видимо перепутал, так удобнее бегать по концу строк, менять value, когда играешься с запросами, так же более выражены AND OR и прочее.

lesha_firs Jun 15 2012 at 06:28

А я так пишу, удобней комментировать условия для отладки.

SELECT
tb1.*,
tb2.*
FROM
tb1
left join tb2 on tb1.id = tb2.id
WHERE
tb1.`date` = '2012-06-15' and
tb2.`date` = '2012-06-15' and
tb1.cat = 1

vitalets Jun 15 2012 at 16:27

Я в последнее время после where всегда единицу ставлю, так удобней если какое-то условие закомментить нужно:

SELECT *
FROM tbl
INNER JOIN tratata
  ON zozo.zozo = zaza
WHERE 1
  AND a = 1
  AND z = 1000

ferasinka Jun 15 2012 at 03:02

В аду есть специальный котел для тех, кто пишет открывающую фигурную скобку на новой строке :-)

-4

hlx Jun 15 2012 at 03:07

Хм, если честно, я сам всегда писал открывающую фигурную скобку на той же строке, где и сама функция, но сейчас я ограничен стандартами компании :)

Shedal Jun 15 2012 at 04:23

… и он пустует, потому что такие люди в ад не попадают? :)
Если серьёзно, то вот это уж точно является делом привычки. А также, традиций. В Java принято ставить открывающую фигурную скобку на той же строке, в C# — переносить.

lesha_firs Jun 15 2012 at 07:57

Насколько я помню ядро люнекса написано на таких скобках. Давным дано еще когда не было нормальных иде. так было удобней смотреть где открывается функция или условие и где заканчивается. Вот оттуда и понеслось.

VolCh Jun 15 2012 at 08:20

Соблюдение стандартов кодирования важнее субъективного мнения о них. Главное чтобы в одном контексте было одинаково, например для классов и методов на новой строке ставить, а для if, for и т. п. в той же.

frenzytechnix Jun 15 2012 at 12:47

Есть как минимум три соглашения о расстановке фигурных скобок в коде:

BSD style:

 if(x == y)

 {

  something();

 }

GNU style:

 if (x == y)

  {

    something ();

  }

K&R style:

 if (x == y) {

  something();

 }

Какой из них использовать — зависит от соглашений, принятых в компании либо заданных самим языком.
К примеру, в Perl согласно Perl Best Practices рекомендуется использовать K&R style.

VolCh Jun 15 2012 at 13:39

Не редкость и комбинация, когда для одних конструкций (функций, классов, методов например) используется один (BSD), а для других (управление потоком) — другой (K&R).

UFO just landed and posted this here

orionll Jun 17 2012 at 11:11

В аду есть специальный котел для тех, кто разводит такие холивары.

Мое мнение — главное, чтобы везде было одинаково. И пох, с новой строки, или на той же строке.

Anexroid Jun 15 2012 at 03:22

А не хватит ли уже на Хабре писать однотипные статьи по оформлению кода?

Никакой новой инфы, которой не было в over 9000 таких же статей на тему «Как именовать переменные, методы и ставить отступы»

mrjj Jun 15 2012 at 19:53

ага, читаешь интернет — и действительно, зачем столько однотипных статей, читаешь чужой код и понимаешь, что таких статей слишком мало, а каждому второму разработчику нужно стучать МакКоннелом по голове, чтобы не писал щуйни вроде
uuU_NEW+=uuUold-uuOLD

Mezomish Jun 15 2012 at 20:19

Вы подождите, еще про табы/пробелы никто не заикался…
OH SHI~…

IkaR49 Jun 15 2012 at 11:20

Согласитесь, читать такой код:
…
Более приятно, чем
…

Вообще да, согласен с этим правилом, но именно в конкретном примере — не соглашусь. В первом случае пришлось скользнуть глазами по коду, чтобы прочитать, а во втором он сразу весь полностью попал в поле зрения и был понят куда быстрее.

P.S. Интересно, кстати, что раньше подобного за собой не замечал и сам всё всегда расписывал построчно.

hlx Jun 15 2012 at 12:04

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

tagir_valeev Jun 15 2012 at 12:56

> либо порядку их использования внутри метода

Странное правило. Вы предлагаете, чтобы сигнатура метода была завязана на его реализацию? А как же инкапсуляция? А если метод переопределяется, и в переопределённом методе порядок другой?

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

step307 Jun 15 2012 at 13:54

К названиям методов, возвращающих boolean, полезно применять тоже правило что к boolean переменным. А именно:

file->checkViruses()

vs.

file->isVirusFree()
или
file->hasVirus()

vitalets Jun 15 2012 at 16:30

Имена булевых переменных должны быть в утвердительной форме и подразумевать булево значение: done, error, found, finished. Плохо: status, source.

можно еще добавлять is: isDone, isError, isFound

orionll Jun 17 2012 at 11:16

Is иногда грамматически не подходит. К примеру, document.hasErrors, objects.areEqual, page.willBeRemoved

myadzel Jun 18 2012 at 12:25

Один из лучших комментариев, что я видел за последнее время.

mrjj Jun 15 2012 at 19:50

Можно было бы ограничиться последний ссылкой.

Lure_of_Chaos Jun 16 2012 at 01:25

Ребята (и автор) — это, конечно, все очень хорошо, копья ломаны не раз.
Хотел бы заметить совсем другое: нужно при оформлении кода ориентироваться на читающих, а не на всех.
То есть, если это мой единоличный проект, то его код, скорей всего не будут читать (зачем? рынок и без того перенасыщен приложениями и библиотеками), поэтому, имхо, глупо его красиво оформлять. Он должен удовлетворять лично мои потребности.
Если я пишу в команде, то неважно какой там кодстайл используется, важно, чтобы он был и был один. Читать его будет только команда. Новички скорее привыкнут к не очень им нравящемуся стилю, не нужно угождать им.
Если проект с открытыми исходными кодами… Думаю, аналогично. Конечно, потенциально его будут читать больше «левых» людей, но это как бы уже их проблемы.

Т.е. «я не 10$, чтобы всем нравиться» и «овчинка выделки не стоит».

Alex_At_Net Jun 16 2012 at 04:16

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

Gluttton Jun 16 2012 at 22:13

Вот только на практике проще добиться абсолютной точности чем примерной (это и про кирпичи и про программирование).

Derailed Jun 16 2012 at 13:47

Добавлю от себя немножко:

1. Старайтесь избегать условных компиляций, да исключением #indef в заголовках. Если же угораздило вляпаться в мешанину #if, #ifdef, #else и т. п., то старайтесь делать условные блоки как можно короче, оформляйте операторы условной компиляции отступами и (желательно) подробными комментариями.

2. Не используйте табуляцию для оформления кода, заменяйте её пробелами. Если же используете табуляцию, то добейтесь, чтобы у всех участников проекта (сотрудников компании) настройки табуляции одинаковые (у всех должно быть задано использование табуляции с одинаковыми параметрами).

3. Вместо реального кода используйте как можно чаще константы, вычисляемые во время компиляции.

4. Для бекапа и обмена кодом используйте систему управления версиями (SVN, Git, Merqurial).

5. Уделяйте время для ведения сопроводительного дневника проекта — простого текстового файла, где делайте наброски алгоритмов, кратко записывайте, какие изменения были сделаны, описание проблем, замечания по оставшейся работе (todo).

-2

DevMan Jun 17 2012 at 01:04

Не используйте табуляцию для оформления кода, заменяйте её пробелами.

Абсолютная ересь.
Есть code convention, им определяется все.

-2

Lure_of_Chaos Jun 17 2012 at 01:22

Табуляция объективно хуже тем, что не имеет постоянной ширины. В результате код, красиво выровненный с табами = 4 пробела, превращается в дикую лесенку при табах = 2 пробела.

Если нет иных code conventions, использую 2 пробела. Опыт показывает, что это идеал.

DevMan Jun 17 2012 at 05:35

Табуляция объективно хуже

Что русскому здорово, то немцу смерть.
Ваше суждение субъективно. Срача на тему «tab vs space» здесь было достаточно, не хочется устраивать очередной.
Используйте, что угодно, только не возводите это в разряд абсолютной истины.

green_fr Jun 19 2012 at 16:20

Переходя к практике: может кто-нибудь посоветовать настраиваемую утилиту форматирования кода? Потому что всё описанное (в части оформления кода) — это хорошо, но когда стандартные IDE не помогают вообще, сложно разношерстную команду подбить под одни правила. Или там, унаследовав от предыдущей команды сотню классов в произвольном форматировании, не хочется терять часы на форматирование ручками.
P.S. У меня конкретно MatLab, но я готов потратить время на конфигурацию готового продукта. Писать с нуля парсер не готов.

Ryadovoy Jun 20 2012 at 20:10

Наши соглашения о кодировании включают рекомендации из книги Герба Саттера и Андрея Александреску:
Стандарты программирования на C++. 101 правило и рекомендация.

Ryadovoy Jun 20 2012 at 20:29

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

К примеру такое объявление переменных у нас запрещено, т.к. приводит к ошибкам:

int someCounter, someOtherValue = 0;

или условные операторы без скобок также запрещены, т.к. можно дописать что-то, а скобки забыть:

if (someValue == 0)
    WriteTrace("Before do something"); // эта строчка была добавлена позже
    DoSomething(); // ошибка, этот код будет вызываться даже если someValue != 0

Но снижение ошибок не должно быть важнее удобочитаемости, и по этому мы не следуем рекомендации писать константы перед переменными в сравнениях:

if (ERROR_SUCCESS != GetLastError()) // IMHO, снижает читабельность кода

Ryadovoy Jun 20 2012 at 20:46

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

int *somePointer, *anotherPointer;

Но так, как у нас однострочное объявление запрещено, то мы спокойно пишем так, как нам удобно:

int* somePointer;
int* anotherPointer;

Ryadovoy Jun 20 2012 at 20:35

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

Ryadovoy Jun 20 2012 at 20:57

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

Show the best of all time