Как сделать комментарии если операторы самый читаемый

Xcode 9 предоставляет возможность установки по беспроводному каналу для установки adhoc.

enter image description here

Но Apple, кажется, не предоставляет базовую HTML-страницу установки. Итак, нужно создать его, как показано здесь .

Здесь приводится HTML-код такой страницы с этого сайта.




  
   
  Install Geoloqi
  



Congrats! You've been invited to the beta of Geoloqi.
Install the
Geoloqi app

7
задан 2 revs, 2 users 100% 3 June 2009 в 19:32
поделиться

24 ответа

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

9
ответ дан 6 December 2019 в 05:01
поделиться

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

0
ответ дан 6 December 2019 в 05:01
поделиться

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

  • обычно легче читать «положительные» условия, чем отрицания (не условие)

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

     function getRequest ($ req) {
     if (isset ($ req)) {
     return $ req;
     } else {
     вернуть $ _SERVER ['REQUEST_URI'];
     }
    }
    

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

  • необходимо прочитать:

0
ответ дан 6 December 2019 в 05:01
поделиться

Назовите свои переменные / методы таким образом, чтобы комментарий был тривиальным.

Если в вашем if много сложных условных выражений, извлеките это условное выражение в логическую функцию / метод это ясно объясняет, что он делает.

Если вам нужно прокомментировать свои условия, вы, вероятно, на пути к Arrow Anti-pattern .

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

0
ответ дан 6 December 2019 в 05:01
поделиться

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

0
ответ дан 6 December 2019 в 05:01
поделиться

Если ваши переменные правильно названы, ваш оператор if должен быть довольно понятным.

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

Ознакомьтесь с определениями «тактических» и «стратегических» комментариев в этом документе http://www.doc.ic.ac.uk/lab /cplus/c++.rules/chap4.html#sect3

0
ответ дан 6 December 2019 в 05:01
поделиться

См. Этот похожий / идентичный вопрос: Куда помещать комментарии в конструкции IF THEN ELSE

0
ответ дан 6 December 2019 в 05:01
поделиться

Не комментируйте очевидное, если ваша аудитория не является, например, новичками ( 1 ).

0
ответ дан 6 December 2019 в 05:01
поделиться

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

0
ответ дан 6 December 2019 в 05:01
поделиться

Комментарии должны объяснять непонятный код. В большинстве случаев непонятный код следует переписать, чтобы он был понятен. В вашем примере я вообще не вижу необходимости в комментариях. Так что, возможно, ответ на вопрос, как сформулировать ваши комментарии, - это сосредоточиться на том, чтобы сделать код более читабельным, чтобы вам не нужны комментарии.

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

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

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

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

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

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

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

0
ответ дан 6 December 2019 в 05:01
поделиться

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

0
ответ дан 6 December 2019 в 05:01
поделиться

Пример операторов if достаточно прост, чтобы не давать никаких комментариев. Чрезмерное комментирование может быть опасным, потому что тогда вам придется поддерживать не только код, но и комментарии. Для сложных операторов if, у вас есть правильная идея - приклейте комментарий прямо над оператором if.

0
ответ дан 6 December 2019 в 05:01
поделиться

Вторая ссылка на Code Complete: отличная книга, которую обязательно нужно прочитать программистам.

Есть некоторые вещи, которые я хотел бы иметь в виду:

  1. Не повторяйте код : объясните, что он делает в общих чертах.

  2. Никогда не предполагайте, что что-то очевидно ; проясните и объясните код.

  3. Используйте функции, чтобы прояснить ваш смысл по мере необходимости: сделайте имя относящимся к тому, что делается.

  4. Никогда не предполагайте, что код не требует пояснений - даже если он должно быть. Самое главное, никогда не предполагайте, что определенная «идиома» кода будет прочитана кем-то, кто ее понимает: объясните, что делает код.

Как кто-то сказал, не ведите себя отрицательно, если можете: у меня было программирование класс, в котором отрицательная IF не допускается ни при каких обстоятельствах. Если действительно застрял, вы можете использовать свой родной язык (например, английский) в своих интересах. Вместо:

if (!eof(f))

Можно сказать:

if (moreData(f))

В вашем примере я бы использовал что-то вроде этого (если я правильно понимаю):

// Make sure that we have a valid request:
// set it if it is not set already
if ( !$request ) {
    $request = $_SERVER['REQUEST_URI'];
}

Я бы также добавил: не помещайте комментарии в поля . «Коробку» трудно поддерживать и поддерживать в актуальном состоянии: человек тратит больше времени на исправление «коробки» вместо того, чтобы поддерживать комментарии в актуальном состоянии.

1
ответ дан 6 December 2019 в 05:01
поделиться

Я использую эту форму:

// Full Comment
if (condition) {
    action;
    action;
}

Потому что, когда включается сворачивание кода, вы получаете что-то вроде этого:

// Full Comment
if (condition) { ...} [+]

Вместо этого:

// Half Comment
if (condition) { ...} [+] <---button to click to get the rest of the comment
1
ответ дан 6 December 2019 в 05:01
поделиться

В этом нет необходимости. Просто выполните рефакторинг, введя объясняющие переменные :

 if ( (platform.toUpperCase().indexOf("MAC") > -1) &&
      (browser.toUpperCase().indexOf("IE") > -1) &&
       wasInitialized() && resize > 0 )
 {
   // do something
 }

станет:

boolean isMacOs     = platform.toUpperCase().indexOf("MAC") > -1;
boolean isIEBrowser = browser.toUpperCase().indexOf("IE")  > -1;
boolean wasResized  = resize > 0;

if (isMacOs && isIEBrowser && wasInitialized() && wasResized)
{
    // do something
}
1
ответ дан 6 December 2019 в 05:01
поделиться

Это во многом зависит от программиста. Я дам два совета:

Не заявляйте очевидного

Возьмите следующий пример:

// If request doesn't exist
if ( !$request ) {

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

Не думайте, что все разработчики знают то, что знаете вы.

Посмотрите на свой код и представьте, что вы относительный новичок. Вы бы это поняли? Если нет, поясните в комментариях.

1
ответ дан 6 December 2019 в 05:01
поделиться

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

1
ответ дан 6 December 2019 в 05:01
поделиться

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

Однако комментарии, объясняющие , почему код делает то, что он делает, могут быть очень ценными. (При условии, что это не чертовски очевидно; если это так, просто пропустите комментарий.)

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


    if ( !$request ) {
        // If the request isn't set, foo() will barf; the current
        // request is a suitable default.
        $request = $_SERVER['REQUEST_URI'];
    }

Просто убедитесь, что ваши комментарии оправдывают свое собственное существование, а все остальное - подливка.

2
ответ дан 6 December 2019 в 05:01
поделиться

Когда я пишу комментарии к коду, я пытаюсь либо

  1. Объяснить сложную, неочевидную процедуру (идеальный пример - reg ex), либо
  2. Объяснить почему Я делаю то, что делаю.

Посмотрите Код завершен . У МакКоннелла есть отличная глава о комментариях.

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

2
ответ дан 6 December 2019 в 05:01
поделиться

Прочтите книгу Роберта Мартина «Чистый код».

http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

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

2
ответ дан 6 December 2019 в 05:01
поделиться

My recommendation is 'don't state the obvious'.

Reading if ( !$request ) says - if there does not exist a request. I don't need a comment for that.

If you have multiple checks (this || (that && this-too)) I would go for creating a method that returns a boolean with the result. Then your method name is your comment, which typically is better than an actual comment.

5
ответ дан 6 December 2019 в 05:01
поделиться

Using your example, I usually prefer the following style:

if ( !$request ) {
    // The request is not yet set, so retrieve it.
    $request = $_SERVER['REQUEST_URI'];
}

I like to place it inside of the if block to make it look better when there is an else or else if.

if ( !$request ) {
    // The request is not yet set, so retrieve it.
    $request = $_SERVER['REQUEST_URI'];
}
else {
    // Comment about doing something else here.
}
3
ответ дан 6 December 2019 в 05:01
поделиться

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

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

Итог: используйте свое усмотрение.

4
ответ дан 6 December 2019 в 05:01
поделиться

In this particular example I wouldn't bother commenting the if statement -- you are repeating what is said in the code.

I might see a case where the test code is complicated:

if (a == 3 && b && c > 2)

but in that case I would first try to extract a method with a meaningful name:

if (markerIsValid(a, b, c))

Only if that was not possible would I then comment the test.

9
ответ дан 6 December 2019 в 05:01
поделиться
Другие вопросы по тегам:

Похожие вопросы: