Keskustelu: Ohjelmointikysymykset: C#: else-lohkon kommentointitottumukset

Hei,

Miten kommentoitte kokonaisia else-lohkoja? Vedättekö kommentin röyhkeästi lohkojen väliin vai else-lohkon sisään, vai molempien lohkojen kommentit ennen if-lohkoa?

Kirjoittelin yhtä koodipätkää ja tuli jälleen tilanne jossa heitin itselleni muistiksi kommentin else-lohkon tarkoitusksesta ("last one"-kommentti elseä ennen):

/// <summary>
    /// Parse []-separated actions from string
    /// </summary>
    /// <param name="data">Dialogue</param>
    /// <returns>Actions</returns>
    private List<string> ParseActions(string data)
    {
        List<string> result = new List<string>();
        while (data.Length > 0 && data.IndexOf("[") >= 0) {
            int i1 = data.IndexOf("[");
            int i2 = data.IndexOf("[", i1);

            if (i2 != -1)
            {
                result.Add(data.Substring(i1, i2 - i1));
                data = data.Substring(i2);
            }
            //last one
            else
            {
                result.Add(data.Substring(i2));
                return result;
            }
        }
        return result;
    }

Jotenkin tulee olo, että tuollainen välikommentti omalle riville erottaa if ja else lohkot epäselvästi toisistaan.

Itse kirjoittaisin kommentin kielestä riippumatta juuri tuohon else-sanan yläpuolelle eli edelliselle riville.

tkok kirjoitti:

Vedättekö kommentin röyhkeästi lohkojen väliin vai else-lohkon sisään, vai molempien lohkojen kommentit ennen if-lohkoa?

Jos haluan kommentoida nimenomaan else-lohkoa, laitan kommentin tuolla tavalla väliin. En kuitenkaan muista milloin olisin viimeksi nähnyt tarvetta tehdä niin. En ylipäätään käytä paljoa kommentteja, mutta kun käytän, kirjoitan mieluummin yhden korkeamman tason kommentin ennen funktiota tai silmukkaa, jossa selitän algoritmin välivaiheet tai oleelliset tietorakenteet. Koodin pitäisi olla niin selkeää, että yksittäisiä rivejä tai if-ehtoja ei tarvitse selitellä. Mystiset muutaman sanan mittaiset kommentit siellä täällä ovat minusta huonoa tyyliä.

Tuossa koodipätkässä kommentista ei minusta ole mitään hyötyä. Koodin lukemista voisi helpottaa esimerkiksi antamalla esimerkin syötteestä ja paluuarvosta. Minulle "[]-separated" ei sano mitään, varsinkaan kun itse koodissa vain hypitään [-merkistä toiseen eikä välitetä sulkevista hakasuluista ollenkaan. Lisäksi silmukan ehdossa data.Length > 0 on turha, IndexOf:n paluuarvoa vertaillaan ensin ">= 0" ja sitten "!= -1", mikä ei ole yhdenmukaista ja indeksimuuttujien nimet ovat kehnoja.

Jos syöte on muotoa "[abc][def]...[xxx]", silmukka olisi minusta parempi vaikka näin:

List<string> result = new List<string>();
for (int start = data.IndexOf("["); start != -1;) {
   int end = data.IndexOf("]", start);
   if (end == -1) {
      throw something;
   }
   result.Add(data.Substring(start, end - start + 1));
   start = data.Substring("[", end);
}
return result;

Mielestäni if -lohkoja tulee kommentoida vain, jos niiden sisältö ei jostain syystä lukijalle aukene. esimerkiksi muuttujien hyvällä nimeämisellä voi usein korvata kommentoinnin, kuten silmille sopivammalla koodilla tehty toteutuskin.

//esimerkiksi tähän suuntaan:

List<string> result = new List<string>();
string[] delimiters = {"[","]"};
string[] paramsArray = data.Split(delimiters, StringSplitOptions.RemoveEmptyEntries};
foreach(string s in paramsArray)
{
  result.Add(s);
}
return result;

groovyb: Tuotakin voisi vielä selventää tekemällä siitä suoraan one-lineri:

return data.Split(
    new [] { "[", "]" },
    StringSplitOptions.RemoveEmptyEntries).ToList();