55 zabawnych komentarzy, które ktoś naprawdę umieścił w kodzie

Komentarz do kodu ma być czytelnym wyjaśnieniem tego, co dzieje się w określonym bloku lub pliku. Celem komentarza jest przedstawienie innym programistom kontekstu do tego, co się dzieje. Pomaga to poczuć się pewniej podczas wprowadzania zmian i uczynić kod łatwiejszym do zrozumienia. Programiści mogą mieć lekki problem z pisaniem komentarzy, które są jednocześnie zrozumiałe i nie stwierdzają rzeczy oczywistych — niektórzy są w tym lepsi, a niektórzy gorsi. 

Oto lista 55 komentarzy, które różnią się od powyższego opisu. Dobrej zabawy!

// I have no idea what this means as I've copied it from 
Stackoverflow but it seems to work.

// We should really rewrite this as no one will understand it

// [LT] - Updated config. Added 2 lines total = 55
// [JM] - Added validation. Added 6 lines total = 61
// [LT] - Added new checks for user. Added 18 lines total = 79

// abcdefghijklmnopqrstuvwxyz

// [KM] - 12/06/2018  - Added filter for inactive accounts
// [LT] - 05/09/2018  - Added validation to check permissions
// [TL] - 22/11/2018 -  Made a code change

// This code doesn't need a comment

// Important, this rollbacks a users account
public void RollBackCreateUser()
{
         // TODO
}

// This code feels flacky but I don't know how to make it better

// SOS

// I'm 99.9% sure we don't need this but seems scary to delete

// For loop
for (int = 0; i < users.length; i++)
{

acc.amount += 1.99; // Why does it do this?

Rzadko można się spotkać z pytaniami w komentarzach! Powinienem chyba napisać odpowiedź.

// This adds the VAT amount. [LE] - no it doesn't

// Returns 1
return 0;

// Comments go here

// Return value doesn't matter
return "value";

// Liam did this, ask him

// Create's an address
// I think if you remove the comment above it breaks the code

/// <summary>
/// Creates a user account
/// </summary>
/// <param name="acc"></param>
/// <returns>Returns a string</returns>
public int CreateAccount(Account acc)

amount += 0; // This doesn't seem to increase the number

index = 0; // index == 0

SELECT
    acc.AccountID, -- this selects the AccountID

Sam bym nigdy na to nie wpadł!

// Don't bother changing

/// <summary>
/// This is a method
/// </summary>
/// <returns>A lit of users</returns>

// TODO - add comment

// One day we should change the below.

// This is magic I don't know how its working

else
{
      // I don't know what to do in the else
}

// if
if (accounts.length > 0)
{

// for. i= 0;
   for (int i = 0; i < accounts.length; i++)
   {

// I know I've just wrote this but I think we should change it.

// This is a very big method

// This is an interface
interface IMessage
{

index++; //++

// :(

// Please do no touch!!

// 4 Devs worked on this.
pubic class QueueService

// Check GIT commit for comment

catch (Exception ex)
{
     // Log something? or throw error?
}

// Force the IF to work 
if (1 == 1)
{

// Try and avoid calling this method as it's not the best

// C hash tag method
public bool CheckIfActive(User user)
{

// hack for now

// Most of the system uses this so please be careful

// We have no tests for this interface
interface IUserService

{

// TODO remove this function
function addTogether(x) {
     return x + x;
}

/*Sorry I know I shouldn't use !important but I can't figure out a different way to override this */
.error {
       color: red !important;
}

// Ignore this

// Wish we had more time to change this code as I don't like it

finally
{
       // should never happen
}

Nie byłbym taki pewny!

// Code is Autogenerated please do not change

// I'm sorry, I was in a rush. I wish I had more time

// This seems random but it you keep reading it will make sense.

 .panel {
  padding: 5px; /* Adds 5px of padding */
  font-size: 12px; /* Makes font size 12px */
  color: black; /* Color is black */ 
}

// This is a web service

// WHY

/********************* Section 1  **************************/

Podsumowanie

Mam nadzieję, że lektura Ci się podobała. Z mojego doświadczenia wynika, że dodanie dobrego komentarza może być ciężkie. Dla mnie też takie jest. Myślę, że programiści powinni napisać je w taki sposób, że gdyby odwiedzili swój kod za rok, to bez problemu by go zrozumieli.

Poniżej znajduje się kilka wskazówek, którymi kieruję się w swojej obecnej pracy. Mam nadzieję, że przydadzą się one również Tobie.

• Dodaj komentarze do interfejsu, klas i metod. Pracowałem w kilku firmach, które również dodają je do właściwości, co okazało się bardzo pomocne.
• Komentarz może pomóc w przypadku każdej niezrozumiałej i przypadkowej logiki, której nie da się rozbić na mniejsze kawałki. W przeciwnym wypadku lepiej rozbić logikę na kilka mniejszych metod, których nazwy wystarczająco dobrze opiszą to, co się dzieje. Dobry kod się zazwyczaj sam dokumentuje.
• W miarę możliwości dołączaj linki do dokumentacji. Może to nawet być źródło zewnętrzne, takie jak Stack Overlow i generalnie wszystko, co pomogło Ci rozwiązać dany problem. Myślę, że podanie kontekstu zawsze pomaga.
• Jeśli masz język, który obsługuje regiony, spróbuj ich użyć do uporządkowania kodu w bloki. Może się to przydać w przypadku dużych metod. 
• Jeśli korzystasz z API, użyj czegoś w rodzaju swaggera, aby udokumentować żądania i komunikaty odpowiedzi.
• Jeżeli chodzi o metody, to myślę, że dobrą praktyką jest dodanie komentarza dla każdego parametru i zwracanej wartości. Lubię używać stylu XML jak poniżej:

/// <summary>
/// Search's accounts with the given filters
/// </summary>
/// <param name="active">True = Active accounts. False = Non active accounts</param>
/// <param name="spendOver">Get accounts with spend the given amount</param>
/// <returns>A list of filtered account objects</returns>
public List<Account> SearchAccounts(bool active, decimal spendOver)
{

Oryginał tekstu w języku angielskim możesz przeczytać tutaj.