Список @идентификаторов , TODO или что это такое?

#java #cpp #документация #комментарии

Я видел что в некоторых исходных кодах JS например JQuery комментируют так:

// Define a local copy of jQuery


но это просто строка для людей а

// TODO:


это уже обнаруживается большинством IDE но JS не типизированный язык поэтому спрашиваю
про другие например я видел в некоторых исходных кодах на Java (в основном помоему)
или C++ (какой код здесь и придумал) в комментариях вставляют описания определяемых
ф-ции и т.д. примерно (взял с потолка потому что не знаю что это такое и Java) так:

/*
 @function getSquare
 @args:
 @x int 
 @returns int
*/
int getSquare(int);
...
int getSquare(x){
  return x*x;
}


Что это вообще такое за @... все поисковики уже измучал не нашёл мне кажется что
есть и @TODO просто в JS @ можно опускать. Или @ это что то типа директивы препроцессора
в Java (типа # в c++) или это надо применять в документации а не в исходном коде? 
Сильно не пинайте я уже спрашивал  Научиться писать документацию и хорошо комментировать
код только про JS и только @lampa сказал 


  У вас что, на калькуляторе поиск сломался?


а @Котик:


  Ахаха


но это было про JS а этот вопрос про C++ Java etc. Вопрос к профессионалам объясните
что за @... и т.д и какие можно в исходном коде и документации использовать ключевые слова
    

Ответы

Ответ 1

Говоря простым языком, это называется самодокументированием кода в стиле JavaDoc.
Пример:
class Test {

   /**
    * Разделить одно число на другое
    * 
    * @param int x 
    * @param int y
    * @return int
    */
   public int divide(int x, int y)
   {
      return x/y;
   }
}

Где все, что начинается с "собачки" - называется тегами описания. Из примера:
Эти теги, они стандарты. Не нужно придумывать своих.
Самые основные:
Тег @param int x - означает какой параметер будет передам в функцию
Тег @return - означает какое возращаемое значение мы ожидаем
Тег @author - означает кто автор
Тег @copyright - Авторские права
Тег @license - Лицензия
Тег @version - Версия

итд их много, если нужны все в гугл: JavaDoc Style
JavaDoc Style используется не только в Java, но также и в C#/C/C++ и PHP для само-документирования
классов и методов. Некоторые используют даже в JavaScript.
Это нужно для того чтобы, облегчить чтение/понимание кода. Это общепринятый стандарт/правило
для документирования своего кода.


Ответ 2

Ну вот же, документирование кода Java. У Вас действительно поиск сломался?


Ответ 3

Почитайте про полузабытый API Java Taglet

Языки программирования - разница в комментах в зависимости от позиции в строке

#любой_язык #комментарии

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

Ответы

Ответ 1

VB6

В начале:

Rem я комментарий
' я тоже комментарий


А в середине - только такой

ЯКакойТоКод ' а я комментарий


Javascript, только для браузеров (ES6, Annex B)

В начале строки:

// Комментарий
 и это - тоже


В середине - только так:

doSmth(); // комментарий
doSmthElse();  как и это
  НоВотТут --> СноваКод
  // А так - нет
  КакИТут // тоже можно
}


Ответ 2

В Фортране такое было (в конце концов, был заявлен же "любой язык" :) ), например:


C - Комментарий, начинающийся с этого символа, мог располагаться
только в начале строки; 
! - Комментарий, начинающийся с этого    символа, мог начинаться с
любой позиции.


Ответ 3

Все банально, Java

int a = 1;
int b = 2;
//int c = 3;
if (a < b /*&& b < c*/) {
  //TODO:
}


Я правильно вас понял?

Комментарии из c++/cli (dll) в с#

#c_sharp #cpp_cli #комментарии

Как добавить комментарий в C++ CLI, чтобы потом при использовании методов данной
dll в c# можно было видеть комментарии к функциям и параметрам?
    

Ответы

Ответ 1

В .NET для всех языков используется стандартный подход: xml-комментарии, начинающиеся
с трёх символов ///. После компиляции dll будет создан файл xml, содержащий документацию.
При наличии этого файла комментарии к методам данной библиотеки будут видны в C# и
любом другом языке.

Подробнее смотрите по ссылке Документация XML (Visual C++).

Чтобы файл документации создавался в процессе компиляции нужно указывать параметр
/doc компилятора. Смотрите раздел "Установка данного параметра компилятора в среде
разработки Visual Studio".



Не могу не отметить: хоть там и написано, что переведено вручную, но перевод настолько
корявый, что лучше переключаться на английский язык, если вы им владеете. А также могу
посоветовать использовать справочные материалы по другим языкам, например Комментарии
к XML-документации (Руководство по программированию на C#).


Ответ 2

В чистом C++ - никак, вы же через P/Invoke вызываете нативные функции. Можно использовать
библиотеку на Managed C++, и сформировать .xml описание функций, которые в ней содержатся.


Ответ 3

Я бы в сторону XML-документации смотрел (то есть, в отдельном файле), думаю, получится
все необходимое реализовать, но писать этот файл, вероятно, придется, вручную.

Комментарии c++

#cpp #комментарии

В классе определена операция /. Пишу x=a/*this. 

/* интепретируется как комментарий. Что делать?
    

Ответы

Ответ 1

x = a / *this;


или, в Вашем стиле:

x=a/ *this;


А можно ещё вот так:

x=a/(*this);

Как писать коментарии в json-конфиге?

#json #config #комментарии

Есть конфиг файл в формате json. Нужно закоментировать одну строку и попробовать
другое значение. Ну и сопроводиловку для будущего себя накатать. Какой знак за это
отвечает?
    

Ответы

Ответ 1

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


Ответ 2

В JSON5 завезли комментарии.

Поддерживаются как однострочные //, так и многострочные /* */ комментарии.

Источник: https://ru.wikipedia.org/wiki/JSON#JSON5


Ответ 3

так удобнее

{
    "some-key-comment":"comments_comments",
    "some-key-value":"some-value",
}

Мультиязычные комментарии в Java-коде

#java #комментарии

Хочу выложить свой первый проект на GitHub для Android. Проект как на рус. так и
на англ. языке. Код прокомментирован на русском языке, хочу также его прокомментировать
еще и на английском как минимум. Подскажите, как это лучше сделать? Как это делают,
может есть какие-то статьи почитать? Погуглил - толком ничего не нашел. Не в скобках
же писать на английском языке коммент после русского...    

Ответы

Ответ 1

Если проект мультиязычный, то он комментируется ТОЛЬКО на английском языке. Всё.


Ответ 2

\**
 * 
English
 * 
Русский
 */
 class Foo

От какого лица и в какой форме писать комментарии в документации на английском?

#документация #комментарии

Допустим, я пишу комментарий к функции для документации. Мне нужно описать что она
делает. Форматирование пока опустим. Предположим, это функция загрузки файла с сервера.
По-русски я напишу что-то вроде этих вариантов:

/*
 * Функция загрузки файла
 *  или
 * Загрузка файла
 */


Я слабо владею английским. В русском языке принято описывать алгоритм от третьего
лица, но на английском часто встречал описание от второго лица. Как правильно написать
такую функцию на английском? Нужно ли подразумевать 'it' и писать от третьего лица?
Или вовсе писать в неопределенной форме? Сейчас я пишу так:

/*
 * Loads a file
 */

    

Ответы

Ответ 1

Ваш вариант вполне хорош, он описывает что делает функция, как будто мы объясняем
её кому-то используя только комментарии:

/* Loads a file */
/* Processes the queue */
/* Opens a remote resource */


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

/* Load a file */
/* Process the queue */
/* Open a remote resource */


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


Ответ 2

Используйте Simplified Technical English (STE) 
Пишите коммент как commit message в Git:


Update default policies...
Add support for configuring...
Add shared_storage_test methods...
Add CPU arch filter...

Следуйте модели "50/72":


Первая строка: длина первой строки - не более 50 символов  
Вторая строка: пустая  
Третья и следующие: длина ограничена 72 символами

Как писать комментарии к параметрам метода?

#c_sharp #документация #комментарии

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

Ответы

Ответ 1

Есть такая штука - xml-комментарии. Они отличаются от обычных тем, что предваряются
тремя слэшами, а не двумя. Например: 
/// 

/// Описание метода
/// 
/// Описание параметра
/// Ogbcfybt возвращаемого значения
public int SomeMethod(string arg)


Ответ 2

Ставите /// слеша перед именем члена, далее студия сгенерирует вам заглушку для комментариев.
Заполнить ее можно как в примере.
/// 

/// Некоторый метод.
/// 
/// Количество
/// 
public void Method(int count)
{

}

Научиться писать документацию и хорошо комментировать код [закрыт]

#документация #javascript #opensource #комментарии

        
             
                
                    
                        
                            Закрыт. На этот вопрос невозможно дать объективный ответ.
Ответы на него в данный момент не принимаются.
                            
                        
                    
                
                            
                                
                
                        
                            
                        
                    
                        
                            Хотите улучшить этот вопрос? Update the question so it
can be answered with facts and citations by editing this post.
                        
                        Закрыт 1 год назад.
                                                                                
           
                
        
Хочу создать свой проект на JavaScript (уже в работе), затем хочу создать для него
(хоть и бесплатный) сайт где можно будет им поинтересоваться скачать и т.д. Может размещу
на code.google (уже занял место). Суть: Мне рано или поздно придётся написать документацию
(объекты,методы входящие в состав). И мой код должен быть доступен для скачивания (opensource)
и соответственно красив. Где можно найти статьи (или стандарты) для написания документации
и статьи про хорошее комментирование кода.    

Ответы

Ответ 1

Документирование кода не может быть "хорошим" - оно может быть правильным и соответствующим
стандартам.
Например один из них и всесторонне поддерживаемый - JSDoc

По поводу "контроля качества кода" - тут немного сложнее. Дело в том что для разных
спецификаций и диалектов языка - разные стандарты.  И то что мы сейчас понимаем под
JavaScript - это не сам язык, а различные скриптоязыки и диалекты из спецификации ECMAScript
и другое - например JSX итд.
Поэтому выбор "стандарта" - зависит от конкретного проекта. Использовать для контроля
можно 'lint' или 'eslint' - пакеты в npm.
А какие плагины и какие настройки к нему использовать - зависит от используемой спецификации
языка, платформы и фреймфорков.

Как добавить комментарий в документ с разметкой Markdown?

#разметка #комментарии #markdown

Нужно добавить в документ на Markdown комментарии, которые бы не экспортировались
в итоговый документ. 

Есть стандартный html-комментарий:

 


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

Ответы

Ответ 1

Это реализуемо с помощью ярлыка ссылки (link label), с которым не связывается ни
одна ссылка. 
Эти ярлыки ссылок будут вырезаны при экспорте:



(пустая строка)
[comment]: # (comment text)

(пустая строка)
[//]: # (comment text)


Сравните с обычным синтаксисом ссылки:

[link text][label]

[label]: http://ru.stackoverflow.com/questions/ask


В принципе, спецификация Markdown допускает вариант, когда перед комментарием нет
пустой строки, а вместо # используется <>. Проблема в том, что спецификация дырява
как решето, а имеющиеся 28+ реализаций работают по–разному. Добро пожаловать в Markdown!

Проверить работу различных реализаций нам поможет инструментарий Babelmark2, проверяющий
рендеринг разметки Markdown в различных реализациях. (+ — прошли тест, - — не прошли,
? — оставляют неотображаемый мусор в HTML).


Без пустых строк, с <> 13+, 15-
Пустая строка перед, с <> 20+, 8-
Пустая строка перед и после, c <> 20+, 8-
Без пустых строк, с # 13+ 1? 14-
Пустая строка перед, с # 23+ 1? 4-
Пустая строка перед и после, c # 23+ 1? 4-


Согласно проверке, наиболее платформо-независимый вариант — это # и пустая строка
перед комментарием. Пустая строка после комментария не играет роли. В частности, набирающая
популярность строгая спецификация CommonMark, в разработке которой участвует Jeff Atwood,
работает именно с этим вариантом (и не работает с <> и/или без пустой строки)

C этими реализациями нет никакой возможности использовать такие комментарии:


cebe/markdown 1.1.0
cebe/markdown MarkdownExtra 1.1.0
cebe/markdown GFM 1.1.0
s9e\TextFormatter (Fatdown/PHP)


Исследование основано на решении, предложенном участником Magnus на SO.EN.

Доступ к комментариям HTML

Есть ли какая-то возможность взаимодействия с HTML комментариями посредствам JS?
простотекст

P.s. не надо говорить, что лучше использовать display:none. Мне просто чисто теоретически интересно именно взаимодейсвтие с комментами.    

Ответы

Ответ 1

Вот тут пример. jquery там не обязателен, так для мнимого удобства.
С вашего позволения:
text3test

JS:
$(document).ready(function(){
    $("div").each(function(){

    child = this.firstChild;
    while (child){

    // determine the type of the node
    switch (child.nodeType){
      // if the node is a comment node, output its value
      case Node.COMMENT_NODE : alert(child.nodeValue); break;
    }

    // move to the next child node
    child = child.nextSibling;

  }        
    });
});


Ответ 2

чёрт, не успел:
 $('div').contents().each(function(){
    if(this.nodeType == Node.COMMENT_NODE)
    {
        console.log(this.data);
    }
 });


.contents()

Быстрое комментирование строки

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

Ответ

В качестве отправной точки можно поступить, например, следующим образом.
function! GetCommentStyleByFileType() let file_name = buffer_name('%') if file_name =~ '\(\.\|_\)vim' return ["\"", ''] elseif file_name =~ '\.\(bat\|cmd\)' return ['::', ''] elseif file_name =~ '\.\(c\|cpp\|cs\|js\|php\)' return ['//', ''] elseif file_name =~ '\.\(ht\|x\)ml$' return [''] elseif file_name =~ '\.\(lua\|sql\)' return ['--', ''] elseif file_name =~ '\.\(vb\|vbs\)' return ["'", ''] endif return ['#', ''] endfunction au BufEnter * let b:comment = GetCommentStyleByFileType() function! CommentLine() let stsymbol = b:comment[0] let endsymbol = b:comment[1] exe ":sil! norm 0i" . stsymbol . "\A" . endsymbol . "\" endfunction function! UnCommentLine() let file_name = buffer_name('%') let stsymbol = b:comment[0] if file_name =~ '\.\(c\|cpp\|cs\|js\|php\)' let stsymbol = '\/\/' endif let endsymbol = b:comment[1] exe ":sil! norm :s/^\s*" . stsymbol . "//\" exe ":sil! norm :s/\s*" . endsymbol . "\s*$//\" endfunction exe "set =\ec" nnoremap :call CommentLine() inoremap :call CommentLine()i vmap :call CommentLine() exe "set =\eu" nnoremap :call UnCommentLine() inoremap :call UnCommentLine()i vmap :call UnCommentLine()
Так, чтобы закомментировать строку нужно нажать Alt+C, чтобы снять комментирование со строки - Alt+U. Можно забиндить на другое сочетание клавиш, использование Alt+некая_клавиша здесь для примера, ровно как и сами функции, - поэкспериментируйте, возможно сделаете нечто удобное и полезное не только для себя.

Список @идентификаторов , TODO или что это такое?

Я видел что в некоторых исходных кодах JS например JQuery комментируют так:
// Define a local copy of jQuery
но это просто строка для людей а
// TODO:
это уже обнаруживается большинством IDE но JS не типизированный язык поэтому спрашиваю про другие например я видел в некоторых исходных кодах на Java (в основном помоему) или C++ (какой код здесь и придумал) в комментариях вставляют описания определяемых ф-ции и т.д. примерно (взял с потолка потому что не знаю что это такое и Java) так:
/* @function getSquare @args: @x int @returns int */ int getSquare(int); ... int getSquare(x){ return x*x; }
Что это вообще такое за @... все поисковики уже измучал не нашёл мне кажется что есть и @TODO просто в JS @ можно опускать. Или @ это что то типа директивы препроцессора в Java (типа # в c++) или это надо применять в документации а не в исходном коде? Сильно не пинайте я уже спрашивал Научиться писать документацию и хорошо комментировать код только про JS и только @lampa сказал
У вас что, на калькуляторе поиск сломался?
а @Котик:
Ахаха
но это было про JS а этот вопрос про C++ Java etc. Вопрос к профессионалам объясните что за @... и т.д и какие можно в исходном коде и документации использовать ключевые слова

Ответ

Говоря простым языком, это называется самодокументированием кода в стиле JavaDoc Пример: class Test {
/** * Разделить одно число на другое * * @param int x * @param int y * @return int */ public int divide(int x, int y) { return x/y; } } Где все, что начинается с "собачки" - называется тегами описания. Из примера: Эти теги, они стандарты. Не нужно придумывать своих. Самые основные: Тег @param int x - означает какой параметер будет передам в функцию Тег @return - означает какое возращаемое значение мы ожидаем Тег @author - означает кто автор Тег @copyright - Авторские права Тег @license - Лицензия Тег @version - Версия итд их много, если нужны все в гугл: JavaDoc Style JavaDoc Style используется не только в Java, но также и в C#/C/C++ и PHP для само-документирования классов и методов. Некоторые используют даже в JavaScript. Это нужно для того чтобы, облегчить чтение/понимание кода. Это общепринятый стандарт/правило для документирования своего кода.

Языки программирования - разница в комментах в зависимости от позиции в строке

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

Ответ

VB6
В начале:
Rem я комментарий ' я тоже комментарий
А в середине - только такой
ЯКакойТоКод ' а я комментарий
Javascript, только для браузеров (ES6, Annex B)
В начале строки:
// Комментарий и это - тоже
В середине - только так:
doSmth(); // комментарий doSmthElse(); как и это НоВотТут --> СноваКод // А так - нет КакИТут // тоже можно }

Комментарии из c++/cli (dll) в с#

Как добавить комментарий в C++ CLI, чтобы потом при использовании методов данной dll в c# можно было видеть комментарии к функциям и параметрам?

Ответ

В .NET для всех языков используется стандартный подход: xml-комментарии, начинающиеся с трёх символов ///. После компиляции dll будет создан файл xml, содержащий документацию. При наличии этого файла комментарии к методам данной библиотеки будут видны в C# и любом другом языке.
Подробнее смотрите по ссылке Документация XML (Visual C++)
Чтобы файл документации создавался в процессе компиляции нужно указывать параметр /doc компилятора. Смотрите раздел "Установка данного параметра компилятора в среде разработки Visual Studio".

Не могу не отметить: хоть там и написано, что переведено вручную, но перевод настолько корявый, что лучше переключаться на английский язык, если вы им владеете. А также могу посоветовать использовать справочные материалы по другим языкам, например Комментарии к XML-документации (Руководство по программированию на C#)

Комментарии c++

В классе определена операция /. Пишу x=a/*this.
/* интепретируется как комментарий. Что делать?

Ответ

x = a / *this;
или, в Вашем стиле:
x=a/ *this;
А можно ещё вот так:
x=a/(*this);

Как писать коментарии в json-конфиге?

Есть конфиг файл в формате json. Нужно закоментировать одну строку и попробовать другое значение. Ну и сопроводиловку для будущего себя накатать. Какой знак за это отвечает?

Ответ

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

От какого лица и в какой форме писать комментарии в документации на английском?

Допустим, я пишу комментарий к функции для документации. Мне нужно описать что она делает. Форматирование пока опустим. Предположим, это функция загрузки файла с сервера. По-русски я напишу что-то вроде этих вариантов:
/* * Функция загрузки файла * или * Загрузка файла */
Я слабо владею английским. В русском языке принято описывать алгоритм от третьего лица, но на английском часто встречал описание от второго лица. Как правильно написать такую функцию на английском? Нужно ли подразумевать 'it' и писать от третьего лица? Или вовсе писать в неопределенной форме? Сейчас я пишу так:
/* * Loads a file */

Ответ

Ваш вариант вполне хорош, он описывает что делает функция, как будто мы объясняем её кому-то используя только комментарии:
/* Loads a file */ /* Processes the queue */ /* Opens a remote resource */
Второй вариант, который я встречал, это описание того, что мы хотим сделать этой функцией:
/* Load a file */ /* Process the queue */ /* Open a remote resource */
Эти два варианта самые частовстречающиеся, используйте любой, который предпочитаете лично.

Как писать комментарии к параметрам метода?

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

Ответ

Есть такая штука - xml-комментарии. Они отличаются от обычных тем, что предваряются тремя слэшами, а не двумя. Например: ///

/// Описание метода ///

/// Описание параметра /// Ogbcfybt возвращаемого значения public int SomeMethod(string arg)

Как добавить комментарий в документ с разметкой Markdown?

Нужно добавить в документ на Markdown комментарии, которые бы не экспортировались в итоговый документ.
Есть стандартный html-комментарий:

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

Ответ

Это реализуемо с помощью ярлыка ссылки (link label), с которым не связывается ни одна ссылка. Эти ярлыки ссылок будут вырезаны при экспорте:

(пустая строка) [comment]: # (comment text)
(пустая строка) [//]: # (comment text)
Сравните с обычным синтаксисом ссылки:
[link text][label]
[label]: http://ru.stackoverflow.com/questions/ask
В принципе, спецификация Markdown допускает вариант, когда перед комментарием нет пустой строки, а вместо # используется <>. Проблема в том, что спецификация дырява как решето, а имеющиеся 28+ реализаций работают по–разному. Добро пожаловать в Markdown!
Проверить работу различных реализаций нам поможет инструментарий Babelmark2, проверяющий рендеринг разметки Markdown в различных реализациях. (+ — прошли тест, - — не прошли, ? — оставляют неотображаемый мусор в HTML).
Без пустых строк, с <> 13+, 15- Пустая строка перед, с <> 20+, 8- Пустая строка перед и после, c <> 20+, 8- Без пустых строк, с # 13+ 1? 14- Пустая строка перед, с # 23+ 1? 4- Пустая строка перед и после, c # 23+ 1? 4-
Согласно проверке, наиболее платформо-независимый вариант — это # и пустая строка перед комментарием. Пустая строка после комментария не играет роли. В частности, набирающая популярность строгая спецификация CommonMark, в разработке которой участвует Jeff Atwood, работает именно с этим вариантом (и не работает с <> и/или без пустой строки)
C этими реализациями нет никакой возможности использовать такие комментарии:
cebe/markdown 1.1.0 cebe/markdown MarkdownExtra 1.1.0 cebe/markdown GFM 1.1.0 s9e\TextFormatter (Fatdown/PHP)
Исследование основано на решении, предложенном участником Magnus на SO.EN.