Рекомендуемые правила оформления кода

[Пепел Феникса]

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

			if((*cache_it).getIdent()==L_EOF)return cache.back();
			if(cache_it>=cache.end())
				Scan();
			cache_it++;
			return *cache_it;

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

а) Это намек на пьяный код. Если бы Вы читали комментарии, то поняли бы и его.

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

Нормальный человек попытается понять алгоритм - если он верен нужно провести рефакторинг.

я не говорил про переписывание с нуля, но переписать бы стоило.(а пост не видел после правки)

На придирки по транслитерации и им подобные я уже писал в посте # 35.

не видел.
но просто мне лично тяжело читать смесь транслита и английского.

[Человек_Борща]

Я для форматирования использую спец. утилиты. И конечно же стремлюсь форматировать код так же. Поддержу Пепла Феникса в пользу использования минимума комментариев и максимума Человеко-Понятных Имён переменных, методов, функций и т.д. Если не сокращать, давать максимум смысла и коротко изложить, то получается и комментарии не нужны.

Кому нужно, тот разберётся в коде. Нужно знать 3 вещи:
1. Синтаксис
2. Иметь опыт, смекалку и думалку, 2 руки из плеч и голову из шеи.
3. Уметь пользоваться справкой и гуглом.

Документация кода - для кого-то капризного. Комментарии - для себя любимого.

Документация абязана быть там, где вы что-то новое создали(аля класс). А комментарии.. ну йух с ними =) Кому надо, тот разберётся. Все дело в том, кто пишет код.

[Utkin]

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

Ну хоть такой компромисс . Но думаю моя точка зрения понятна.

я не говорил про переписывание с нуля

Ну тут был другой фронт .

а пост не видел после правки

Посмотрите .

А комментарии.. ну йух с ними =) Кому надо, тот разберётся. Все дело в том, кто пишет код.

Вот он традиционный подход . Йух с ним, йух с тем кто его после Вас будет разбирать и крыть Вас матом за то, что Вы вместо табуляции 4-е пробела ставите и ему читать не удобно. Йух со всеми кроме меня любимого. И я как-то тоже раньше так считал, пока не начал пересматривать тоже что и я написал пару лет назад.

[Пепел Феникса]

Комментарии - для себя любимого.

еще для команды.

[MaTBeu]

Сообщение от Utkin

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

     много кода...

Это начало функции. Я думаю для данного фрагмента комментарии для Вас будут абсолютно излишними.

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

По мне, так следующий стиль более понятен, нежели комментирование каждой строки

/*******************************************************************************
 * Copyright (c) 2011 Azigo Inc.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     Azigo Inc. - initial API and implementation
 ******************************************************************************/
dojo.provide("higgins.pds.client.model.vo.ContextVO");

/**
 * @class higgins.pds.client.model.vo.ContextVO
 * @description Class for holding ANZO context graphs
 */
higgins.pds.client.model.vo.ContextVO = new Class({

    /**
     * @constructor
	 * @public
	 * @memberOf higgins.pds.client.model.vo.ContextVO
	 * @function
	 * @param {ContextGraph} contextGraph to place in new Context object
	 * @returns {void}
     */
    initialize: function(contextGraph) {
        this.log = higgins.common.Utils.getLog("ContextVO");
        this.contextGraph = contextGraph;
        this.log.debug("context graph:" + this.contextGraph);
    },
	
	/**
	 * @private
	 * @memberOf higgins.pds.client.model.vo.ContextVO
	 * @field contextGraph
	 * @type {ContextGraph}
	 * @description context graph object to store in ANZO storage
     */
    contextGraph: null,
	
	/**
	 * @private
	 * @memberOf higgins.pds.client.model.vo.ContextVO
	 * @field log
	 * @type {higgins.common.utils.log.Logger}
	 * @description logger
     */
    log: null,

	/**
	 * @public
	 * @memberOf higgins.pds.client.model.vo.ContextVO
	 * @function
	 * @returns {Object} URI from selected context object
	 * @description Returns URI from current context object to handle save or update actions
     */
    getURI: function() {
        return this.contextGraph.namedGraphUri;
    },

	/**
	 * @public
	 * @memberOf higgins.pds.client.model.vo.ContextVO
	 * @function
	 * @param {higgins.pds.client.model.vo.EntityVO} entity to add to context
	 * @param {higgins.pds.client.model.vo.AttributeVO} attribute to add to specified entity
	 * @param {String} value of attribute to add to specified entity
	 * @returns {void}
	 * @description Adds new tuple to context which contains entity with attribute with or without value. Attribute value (3rd arument) is optional
     */
    add: function() {
        if (arguments[2] != null) {
            this.contextGraph.add(arguments[0] + "", arguments[1] + "", arguments[2] + "");
        } else {
            this.contextGraph.add(this.contextGraph.namedGraphUri, arguments[0] + "", arguments[1] + "");
        }
    },

	/**
	 * @public
	 * @memberOf higgins.pds.client.model.vo.ContextVO
	 * @function
	 * @param {String} propURI - URI to find atribute in context object
	 * @returns {Array} values
	 * @description Returns array of values for specified attribute or empty array
     */
    get: function(propURI) {
        var v = this.contextGraph.find(this.contextGraph.namedGraphUri.value, propURI, null);
        var values = [];
        for (var i = 0; i < v.length; ++i) {
            values[i] = v[i].object;
        }
        return values;
    },

	/**
	 * @public
	 * @memberOf higgins.pds.client.model.vo.ContextVO
	 * @function
	 * @param {String} subject
	 * @param {String} predicate
	 * @param {Object} object
	 * @returns {Array<Object>} values
	 * @description Returns array of objects with or without values for specified subject, predicate and object. All arguments are optional
     */
    find: function(subject, predicate, object) {
        if (null != subject) {
            subject = subject + "";
        }
        if (null != predicate) {
            predicate = predicate + "";
        }
        if (null != object) {
            object = object + "";
        }
        return this.contextGraph.find(subject, predicate, object);
    },
    // more core here
});

Взято из OpenSource проекта под названием Higgins (на котором я недавно работал).

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

И да - этот код не претендует на звание идеального. Но он неплохо документирован, что облегчает его понимание.

P.S. кто не понял - это JavaScript.

[Utkin]

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

И тем не менее Пепел Феникса ухватил суть.

По мне, так следующий стиль более понятен, нежели комментирование каждой строки

Это Ваше право (заметьте, я допускаю, что точка зрения отличная от моей не является студенческой). Плюс наверняка работа в команде была подчинена определенному внутреннему стандарту (команды, фирмы), если конечно была работа в команде .

[MaTBeu]

Сообщение от Utkin

И тем не менее Пепел Феникса ухватил суть.

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

Сообщение от Utkin

Это Ваше право (заметьте, я допускаю, что точка зрения отличная от моей не является студенческой). Плюс наверняка работа в команде была подчинена определенному внутреннему стандарту (команды, фирмы).

Не придирайтесь к словам. Я уже написал про студенческий стиль.

Работа в команде не была подчинена внутреннему стандарту. Это была инциатива как моя, так и отдельных разработчиков. Просто в какой-то момент я стал писать такие комментарии и получилось сделать код понятнее, вот и все.

[Utkin]

Не придирайтесь к словам.

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

[MaTBeu]

Сообщение от Utkin

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

Вот здесь, если что

Сообщение от Utkin

Это Ваше право (заметьте, я допускаю, что точка зрения отличная от моей не является студенческой).

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

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

[Человек_Борща]

Вот он традиционный подход . Йух с ним, йух с тем кто его после Вас будет разбирать и крыть Вас матом за то, что Вы вместо табуляции 4-е пробела ставите и ему читать не удобно. Йух со всеми кроме меня любимого. И я как-то тоже раньше так считал, пока не начал пересматривать тоже что и я написал пару лет назад.

Я не призываю Не комментировать код совсем. Какраз рна оборот. Я ставлю на следующего анонимуса с расчётом на то, что анонимус будет умный, будет знать синтаксис, будет знать английский язык, будет уметь пользоваться справкой. Зачем мне комментировать очевидные действия? Зачем комментировать, что делать такой-то метод такого-то стандартного класса? Я просто делаю отсылку туда-то, например в справку или такой-то модуль с таким-то классом.

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