Courvoisier

|

Courvoisier

the rapidly dwindling sanity of valve programmers as expressed through code comments

Аз не слагам често коментари, но когато слагам са такива.

Бях при едни, искаха всеки Public метод да е с документация. Аз им поспорих, че ако пишем с идеята да се чете, няма да има нужда за който чете, а за който не чете няма да има смисъл и от коментари. Продължихме така половин година. И за ташак пишех

// get pending orders ordered by timestamp ascending
GetPendingOrdersByTimestamp

// ....

// compare two object (hint: icomparable sorting haha)
public int CompareTo(MyObject other)
{
    if (IsEqual(other))
        return 0;
    else if (IsGreater(other))
        return -1;
    else
        return 1;
}

Некви такива простотии...

Е, аз пиша доста опън сорс, затова обикновено коментирам публичните функции. Иначе в кода слагам коментари на места където след две месеца, когато съм забравил детайлите ще се чудя какво става. На местата, където правя някаква глупост, защото нямам време/желание да го напиша както трябва задължително слагам някакъв подобен коментар, за да не се чудя след два месеца дали кода има някакъв скрит смисъл. :)

relax4o

Ние избягваме да коментираме по методите, защото когато нещо се промени след това никой не ъпдейтва коментара и само бърка четящия.

Ако метода е по-комплексен и не се вижда от пръв поглед какво прави (или името е неясно) се обославяме, но като цяло избягваме.

И това го има Даже съм писал документация в readme, след мене променяли, никой не барнал документацията.

А като имам по- комплексен метод, гледам да го цепя. Избягвам да имам методи над 20 реда. Ламдите ги изкарвам на методи, даже

if(obj.isSomething && obj.size > 256 && obj.alabala == "neshto si")

го изнасям в

if(IsObjectMeetingCriteria(obj))

// ....

bool IsObjectMeetingCriteria(MyObject obj) 
{
    return obj.isSomething
        && obj.size > 256
        && obj.alabala == "neshto si"
}

ПС: Меджик нъмбъра и меджик стринга са там за простота на изказа .

Courvoisier

relax4o

Ние избягваме да коментираме по методите, защото когато нещо се промени след това никой не ъпдейтва коментара и само бърка четящия.

Ако метода е по-комплексен и не се вижда от пръв поглед какво прави (или името е неясно) се обославяме, но като цяло избягваме.

И това го има Даже съм писал документация в readme, след мене променяли, никой не барнал документацията.

А като имам по- комплексен метод, гледам да го цепя. Избягвам да имам методи над 20 реда. Ламдите ги изкарвам на методи, даже

if(obj.isSomething && obj.size > 256 && obj.alabala == "neshto si")

го изнасям в

if(IsObjectMeetingCriteria(obj))

// ....

bool IsObjectMeetingCriteria(MyObject obj) 
{
    return obj.isSomething
        && obj.size > 256
        && obj.alabala == "neshto si"
}

ПС: Меджик нъмбъра и меджик стринга са там за простота на изказа .

Това е прекалено, човешкия мозък също има проблеми с дълбочината на стека.

Де да знам всъщност, може би IDE-тата помагат в такива случаи, и затова хората ги използват? Една от мистериите на Вселената. :)

ПС: Опенсорс да, библиотеки, но пък аз вярвам, че по- скоро трябва да се пише четим код от хора за хора. Едни такива GNU-джендър утопии. Така ми го набиха в университета дъ дейнс, уеър самтинг ис ротън и се индоктринирах в тази вяра. Колкото и да чета коментара, накрая пак ще чета кода, по- добре да е написан четимо.

Преди време бачках с едни индуси, много ме кефеше да отварям клас, 2/3 коментиран код, от останалата 1/3 половината е дед код, другата половина се ползва и набивали по 10 нови реда на рандом места

Аз помня много ако съм го писал, но може би защото съм още в 30-те, даже скоро ги почнах. Е сега имам около 100 класа, всичките ги помня, от понеделник съм ги записал, днес си играя с дженкинса да го качва. Обаче стига толкова за днес...

И гледам когнитивното комплексити, sonarqube ми го мери, гледам да не го вдигам много. Така и ми е по- лесно като гръмне някъде да знам по стека какво точно е гръмнало. А и името на метода ми е коментар.

Courvoisier

if(obj.isSomething && obj.size > 256 && obj.alabala == "neshto si")

го изнасям в

if(IsObjectMeetingCriteria(obj))

// ....

bool IsObjectMeetingCriteria(MyObject obj) 
{
    return obj.isSomething
        && obj.size > 256
        && obj.alabala == "neshto si"
}

ПС: Меджик нъмбъра и меджик стринга са там за простота на изказа .

Ако ще използвам проверката само на едно място, ще я изнеса най-много в променлива за четимост.

От скоро гледам CQRS, правя го в application-а с getter-и, да Верно е по- natural.

Типичен коментар, писах го вчера:

        if len(dss) > 32 {      // FIXME: not sure what number to put here
                maxidx = 2      // FIXME: not sure what number to put here either
        }

Един от моите:

// FIXME: Just hacking. It seems to be working for now.
if (blah blah) {
    // ...
}

Major Obvious

Courvoisier

ПС: Бендъра май не влиза вече, но ако някога види цитат от Еклесиаст в нетаджийски код, да знае, че аз съм го оставил за друг посветен в соломоновата мъдрост. Лехаим!

Бендера сега е ФейкПрофил.

Упорито отрича от day one.

Delegate

Major Obvious

Courvoisier

ПС: Бендъра май не влиза вече, но ако някога види цитат от Еклесиаст в нетаджийски код, да знае, че аз съм го оставил за друг посветен в соломоновата мъдрост. Лехаим!

Бендера сега е ФейкПрофил.

Упорито отрича от day one.

Бендера винаги отрича. Това е един от признаците, че е той.

Delegate

Упорито отрича от day one.

Ми да отрича, ама фингърпринта не лъже.