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

Question

Привет У меня есть 50 страниц кода, которые я должен написать ему ... Можете ли вы, ребята, показать мне лучший способ. Я имел в виду, я хочу, чтобы ты написать мне образец ... комментарии должны содержать почти все (классы, конструкторы, атрибут, методы, события, функции)

Answer 1

Не комментируйте то, что очевидно, как

//The width of the line is 2 
lineWidth = 2; 

или

//Clones the snapshot 
tempDraw = (Bitmap)snapshot.Clone(); 

Там может быть хорошей идеей, чтобы объяснить, почему определенная строка кода есть. Например, объясните причину.

panel1.Invalidate(); 

Необходимо быть недействительным.

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

EDIT:

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

private void toolStripButton1_Click(object sender, EventArgs e) 
{ 
    foreach (ToolStripButton btn in toolStrip1.Items) 
    { 
     btn.Checked = false; 
    } 
... 
} 

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

Хороший комментарий будет что-то вроде:

private void toolStripButton1_Click(object sender, EventArgs e) 
{ 
    //Deselect all previously applied filters because the user clicked "disable all", 
    //which removes the effects of all filters and we want to show this the the user 
    foreach (ToolStripButton btn in toolStrip1.Items) 
    { 
     btn.Checked = false; 
    } 
... 
} 

Answer 2

Хорошие комментарии будут документировать намерения, не функция.

В основном бесполезно комментировать назначения с помощью «назначить x на y» или аналогичного.

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

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

Answer 3

Я рекомендую вам использовать комментарии XML в Visual Studio. При этом вы также можете автоматически генерировать документацию для своего кода, а также другие разработчики могут видеть, какой метод делает то, что через intellisense.

http://www.winnershtriangle.com/w/Articles.XMLCommentsInCSharp.asp

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

Answer 4

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

Ваша форма1 (плохое имя, b.t.w.) делает слишком много. Он должен попросить другие объекты, чтобы помочь ему. Возможно, вам захочется ввести класс инструмента, который знает, какой текст и курсор этикеток подходят. Возможно, вы захотите использовать наследование для разных фигур, чтобы сделать рисунок в форме. Таким образом, ваш Form1 должен только делегировать текущий инструмент.

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

Answer 5

Я на самом деле просто написал blog post on this subject. Имейте в виду, что на 100% возможно (но, возможно, не предпочтительнее) для кода, который не содержит комментариев и может быть легко читаемым.