Programmering i andras ögon?

library ieee;
    use ieee.std_logic_1164.all;
    use ieee.numeric_std.all;

entity mac is
  port(clk : in  std_logic;
        ds : in  std_logic;
        a  : in  std_logic_vector(15 downto 0);
        b  : in  std_logic_vector(15 downto 0);
        p  : out std_logic_vector(47 downto 0);
end entity;

architecture vhdl of mac is
   signal pi : signed(p'range):=(others=>'0');
begin
   p<=std_logic_vector(pi);
   process(clk)
   begin
      if rising_edge(clk) then
         if ds='1' then
            pi<=resize(signed(a)*signed(b),pi'length);
         else
            pi<=signed(a)*signed(b)+pi;
         end if;
      end if;
   end process;
end architecture;

VHDL?
Ser ut som att du skickar in två vektorer på 16 med boleaner och skickar ut en på 48.
pi (p internal?) sätts till samma längd som utvektorn.
utvektorn är ständigt std_logic_vector(pi).
process(clk) körs när clk sätts.
Vad är ds?
Vet inte vad resize() gör.
signed() och std_logic_vector(p), är typkonverteringar, boolean till integer och tillbaka?
'size är vektorns längd och 'range dess storlek.

Ett bra exempel på ett program, som skulle må bra av bättre variabelnamn och fler kommentarer.

För små projekt, typ det du länkar till, är det fullt möjligt att lura ut hur saker ska användas helt utan dokumentation. Är fortfarande lättare med vettig API-dokumentation, men skillnaden blir mindre ju mindre APIet är. Javas/.NETs bibliotek skulle i praktiken vara oanvändbara utan dokumentation för extrem få skulle orka försöka lura ut vilken ände man ens ska titta i.

Clonar jag ditt projekt så kan jag från namnen på biblioteken rätt lätt gissa det nog är SignalR.EventAggregatorProxy.Client.DotNet jag ska börja gräva.
Gissar också att SignalR.EventAggregatorProxy är någon form av server efter som den inte har "Client.<ramverk>". Båda biblioteken har ett underbibliotek Bootstrap, är allt annat än klart hur det ska användas (och det är kliniskt rent från dokumentation). Fick man sitta med det här ett tag så tvivlar jag inte en sekund på att man lurar ut hur det ska används, är ju ett rätt litet projekt. Utan att verkligen lusläsa koden så kommer man hålla på med "Programming by Coincidence", vilket tyvärr ofta fungerar så pass bra för enklare uppgifter att många tror att det är ett icke-problem.

Efter att tittat lite C# API-markup så undrar man ju här de tänkte här, XML är ju totalt hjärndött för detta ändamål då det om något skapar rejält mycket mer brus än t.ex. JavaDoc markup.Så kan förstå om C# programmerar drar sig för att använda det, tycker personligen att JavaDoc är så enkelt att använda att det inte finns några rationella anledningar att försöka undvika det.

Säg att man vill implementera TCP och just nu jobbar med flödeskontroll som bl.a. beskrivs i RFC5681, skulle du då hellre se detta

uint32_t GetInitialCongestionWindow(const TransmissionControlBlock *tcb)
{
    uint32_t initialWindow;
    uint32_t smss = GetSenderMaximumSegmentSize(tcb);

    if (smss > 2190) {
        initialWindow = 2 * smss;
    } else if (smss > 1095) {
        initialWindow = 3 * smss;
    } else {
        initialWindow = 4 * smss;
    }
    return initialWindow;
}

eller

/*
 * Get initial sender congestion window. The initial congestion window
 * must be used as the sender maximum segment size, SMSS, for newly
 * created TCP sessions.
 *
 * @param tcb   Transmission control block for the TCP session
 * @return      Initial sender congestion window
 */
uint32_t iwGet(const tcb_t *tcb)
{
    uint32_t iw;
    uint32_t smss = smssGet(tcb);

    /*
     * RFC5681, chapter 3.1
     *
     * IW, the initial value of cwnd, MUST be set using the following
     * guidelines as an upper bound.
     *
     * If SMSS > 2190 bytes:
     *     IW = 2 * SMSS bytes and MUST NOT be more than 2 segments
     * If (SMSS > 1095 bytes) and (SMSS <= 2190 bytes):
     *     IW = 3 * SMSS bytes and MUST NOT be more than 3 segments
     * if SMSS <= 1095 bytes:
     *     IW = 4 * SMSS bytes and MUST NOT be more than 4 segments
     */
    if (smss > 2190) {
        iw = 2 * smss;
    } else if (smss > 1095) {
        iw = 3 * smss;
    } else {
        iw = 4 * smss;
    }
    return iw;
}

Finns ingen anledning att använda speciellt långa namn när man kommenterar koden, mycket bättre att köra med korta namn som är "to the point" på både variabler och funktioner då det är uppenbart vad de representerar från dokumentationen. Det första exemplet har ju överhuvudtaget ingen förklaring för sin läsare vad 2190 och 1095, visst skulle man kunna namnge dessa konstanter men till vad då, RFC5681_LARGE_SMSS och RFC5681_SMALL_SMSS? Säger fortfarande absolut inget om varför man har sin if-drapa eller ens varför funktion behövs.

Ja, att refaktorisera och göra koden mer läslig med bättre struktur och bra namngivning av variabler osv är oftast mycket mer värt än att skriva kommentarer. Sitter man och skriver kod och tänker "Aj, aj, nu börjar det bli lite ointuitivt och invecklat. Det är bäst att jag skriver en kommentar så att folk förstår.", så är det nästan alltid tecken på att man borde omstrukturera koden istället.

Har man en funktion eller klass så kan det dock vara en god ide att dokumentera den innan själva koden börjar med att beskriva vad den gör, vad den returnerar, eventuellla brister osv.
Väl inne i koden så förstör dock kommentarer läsligheten en hel del, speciellt om det rör sig om många och långa kommentarer.
En enstaka enradskommentar där det verkligen gör nytta är väl ingen katastrof, men man bör inte slentrianmässigt skriva kommentarer överallt.

Har man däremot extremt rörig kod så är det antagligen värre att inte ha kommentarer än att ha det, men då är inte bristen på kommentarer det stora problemet...

Håller helt med.
Det är lätt att tänka att ett långt namn som säger exakt vad variabeln är borde vara väldigt pedagogiskt.
Efter att man skrivit variabelnamnet ett antal gånger och efter en snabb koll på hur koden ser ut när man skrivit klart är det dock väldigt lätt att ändra uppfattning...
Koden blir ofta väldigt jobbig att läsa om alla variabelnamn är mindre uppsatser, speciellt om man skriver matematiska formler där de ingår. Dessutom är det jobbigt att skriva koden.
Alltför långa variabelnamn förstör oftast läsligheten på samma sätt som tonvis med insprängda kommentarer i koden.

Sedan kan man naturligtvis bli extrem åt andra hållet och göra för korta variabelnamn (typ en bokstav) när de borde vara något längre, eller iallafall mer tydliga så att det blir uppenbart vad variabeln står för. Variabelnamn som är en bokstav kan vara ok om det rör sig om någon lokal hjälpvariabel där det är uppenbart vad variabeln gör eller om variabeln betecknar någon känd kvantitet som så gott som alltid förkortas till denna bokstav.

Jag och fem vänner försökte i 6:an tvinga skolan att acceptera vårt språkval.
Vi hade valt C++. Efter ett år så var de trötta på oss och tvingade in oss i en Spanskaklass.

Håller med. Det var lite det jag försökte uttrycka när jag skrev att korta variabelnamn kan vara ok om de används väldigt lokalt i koden.