Tool om programma ordelijk te houden en te beginnen


Op 18 augustus 2019 18:30:36 schreef MJU:
Ik onthou dat ik beter manueel (op papier) alles noteer.
Ben ik wel wat chaotisch voor.. maar ga het proberen.

Moest je mijn krabbels zien dan zou je denken hoe geraakt die eruit ;) maar dat is nu eenmaal mijn werkwijze.
Tekeningen maken met de computer duurt mij te lang, met de vrije hand gaat het veel veel sneller .. en ik heb een goede scanner.

Op de computer worden alle documenten van dat project in 1map gezet, als ik die map opendoe staat alles wat ik nodig heb gehad(of heb) om dat programma te maken, gemaakte foto's, scans, filmpjes, inclusief stukken van datasheets en natuurlijk de sourcecode en de gecompileerde files.

In principe moet ik dan nergens meer gaan zoeken wat ik bv 10j geleden heb gemaakt of gebruikt voor dat project, alles staat in die map.
Als je dat vanaf het begin van het project doet is het heel makkelijk te onderhouden en na een tijdje krijg je daar een soort routine in.

LDmicro user.
High met Henk

Special Member

er is ook DOXYGEN

heb er wel eens naar gekeken, en het is EEN idee.

to all newbies: RTFM/D of google eens (p.s. RTFM/D = Read the f*cking manual/datasheet).

Er is hierop geen algemeen antwoord mogelijk, het hangt heel erg af van de programmeertaal en van het O/S (als er al een is).

Voorbeeld: In Unix, en al wat er is van afgeleid tot en met Raspbian, is het een uitgangspunt om een totaalopdracht zoveel mogelijk op te delen in deelprocessen, die elks onafhankelijk draaien, en met elkaar communiceren via bestanden en/of pipes en/of semaphores. Andere O/S, begonnen als single-tasking, maken nog steeds 1 executable die dan alles tegelijk/doorelkaar moet doen.

Ook: als je C schrijft kun je stukken broncode afzonderen in "include"-bestanden; erg handig, als je complexe dingen schrijft. Je hoofdprogramma omvat dan nog maar enkel de hoofdlus, of zelfs dat niet, en een reeks includes. Iet of wat assembler kan dat ook wel aan, denk ik. In python gaat dat niet, daar kun je enkel nog je functiedeclaraties in een eigen library stoppen en die dan importeren.

Als illustratie: ik werk aan een eigen "moving map" onder Raspbian; dat omvat enerzijds een python script, dat gnss-data inleest en wegschrijft in enkele bestandjes, en anderszijds een redelijk complex C-programma dat verschillende lagen van de map op scherm brengt, voor elke laag is er een #include. En de hoofdlus begint natuurlijk met het lezen van de gnss-informatie uit de bestandjes die de python geschreven heeft.

En enkele bedenkingen bij vorige bijdragen:

Als je bij een blok(je) code omschrijft wat dat doet heb je daar veel meer aan...

Inderdaad. Bij wijze van boutade kan men stellen dat perfect geschreven code helemaal geen commentaar bevat, wegens overbodig. Bij mij kun je nog wel eens iets lezen als "ptr-- //pointer was reeds impliciet verhoogd maar dat hoeft hier niet"

Moest je mijn krabbels zien dan zou je denken hoe geraakt die eruit

Dat maakt me benieuwd :) Maar inderdaad het is allemaal maar een kwestie van gewoontes. Zichzelf een beetje opvoeden, af en toe...

[Bericht gewijzigd door big_fat_mama op 18 augustus 2019 20:26:32 (18%)]

hoe beter de vraag geschreven, zoveel te meer kans op goed antwoord

Op 18 augustus 2019 19:56:26 schreef High met Henk:
er is ook DOXYGEN

heb er wel eens naar gekeken, en het is EEN idee.

Het nodigt uit om commentaar/documentatie te schrijven waar je helemaal NIETS aan hebt.

code:


/**
 * @name    Serial status flags
 * @{
 */
#define SD_PARITY_ERROR         (eventflags_t)32    /**< @brief Parity.     */
#define SD_FRAMING_ERROR        (eventflags_t)64    /**< @brief Framing.    */
#define SD_OVERRUN_ERROR        (eventflags_t)128   /**< @brief Overflow.   */
#define SD_NOISE_ERROR          (eventflags_t)256   /**< @brief Line noise. */
#define SD_BREAK_DETECTED       (eventflags_t)512   /**< @brief LIN Break.  */
/** @} */

Wat heb ik aan het commentaar dat dit constantes zijn? waar worden ze gebruikt? Wat heb ik aan de documentatie "Parity." bij de constante "SD_PARITY_ERROR". De code geeft in ieder geval aan dat het een ERROR betreft.

four NANDS do make a NOR . Kijk ook eens in onze shop: http://www.bitwizard.nl/shop/
buckfast_beekeeper

Golden Member

Op 18 augustus 2019 10:43:15 schreef K7Jz:
Het handigste is toch echt in de code zelf duidelijk werken:

Geen loops of if elses die meer dan 5 - 10 regels doorlopen.

Geen nietszeggende variabelen als:
Count, x, i, a.

Code kort houden:

If leessensor(TEMPERATUUR)>MIN_TEMPERATUUR

Leest sneller dan:

X = readInputPin(3)
Y = 5

If X>Y

Etcetera.

Grote projecten werken vaak modulair. Er is dan wel discipline nodig. Als een module iets niet ondersteund dan is het meer werk alles aan te passen dan direct in de spaghetticode iets erbij te proppen.

Over de nietszeggende variabelen ben ik het niet 100% eens.

c code:


For(int x=0, x<100; x++){
    System.out.println(x);
}

Wie daar niet mee overweg kan moet maar wat anders gaan doen.

@TS: gebruik zinvolle namen.
Zoals hierboven ook al aangehaald geen zinloze commentaar. Bij functies en procedures zet ik er wel kort boven wat de functie/procedure doet wat de zaken zijn dat de input is en wat de eventuele output is.

Honing kan je importeren, bestuiving niet.
bprosman

Golden Member

Over de nietszeggende variabelen ben ik het niet 100% eens

Niet alles is zwart/wit, er zijn nog minstens 50 tinten grijs.

Voor een looptellertje of een tijdelijke variabele is er niets mis mee om een X, Y oid te gebruiken, dat lees je er ook zo uit.

Voor een temperatuur inlezen oid zou ik het dan weer niet doen.

De jongere generatie loopt veel te vaak zijn PIC achterna.

Op 19 augustus 2019 08:51:48 schreef rew:
[...]

Het nodigt uit om commentaar/documentatie te schrijven waar je helemaal NIETS aan hebt.

Wat heb ik aan het commentaar dat dit constantes zijn? waar worden ze gebruikt? Wat heb ik aan de documentatie "Parity." bij de constante "SD_PARITY_ERROR".

Zoals voor alles geldt ook voor deze tools, "A fool with a tool is still a fool"

De door jouw aangehaalde voorbeelden zijn natuurlijk geen 'representatieve' voorbeelden voor het gebruik van commentaar.

DoxyGen heeft veel mogelijkheden om documentatie op een gestructureerde manier op de bouwen. Inclusief, functiecalls, parameter, statemachines etc.

Als je gewend bent om commentaar zoals "Dit is variabale error" zal een tool je niet verder helpen ......

Op 18 augustus 2019 20:09:27 schreef big_fat_mama:
[...]Dat maakt me benieuwd :) Maar inderdaad het is allemaal maar een kwestie van gewoontes. Zichzelf een beetje opvoeden, af en toe...

Ben te oud om heropgevoed te worden.
Hieronder een klein deeltje van mijn verzameling om aan uw nieuwsgierigheid te voldoen en het is allemaal copyright :)

Maar vergis u niet alle papiertjes zitten netjes in fardes.

LDmicro user.

Op 19 augustus 2019 09:53:27 schreef wvdakker:
DoxyGen heeft veel mogelijkheden om documentatie op een gestructureerde manier op de bouwen. Inclusief, functiecalls, parameter, statemachines etc.

Maar mijn kritiek is: "Het NODIGT UIT om nietszeggende docu te maken". En in mijn ervaring is dat 100% het geval in de projecten die doxygen gebruiken. Maar d'r zullen best tegenvoorbeelden zijn. Dat ontken ik niet. Er zullen mensen zijn die zich tegen de "uitnodiging" kunnen verzetten.

De reden is dat je de docu inline met de code schrijft. Datgene wat obvious is in het bestand met de code wordt als je het met doxygen tot losse docue maakt ineens noodzakelijk extra commentaar.

Even voor de goede orde: Ik vind doxygen een foute tool. Het resulteert in slechte docu. Dus ik gebruik het niet zelf. Ik loop er alleen tegenaan als een library of zoiets die ik wil gebruiken het gebruikt.

[Bericht gewijzigd door rew op 19 augustus 2019 10:13:01 (13%)]

four NANDS do make a NOR . Kijk ook eens in onze shop: http://www.bitwizard.nl/shop/

Programmeren is ook niet meteen mijn bezigheid. Met projecten waar ik aan werk hou ik een "dagboek" bij met ideeën en resultaten.

Met programmeren werk ik met modules die je in een programma kunt implementeren.
Zo had ik laatst een LCD dat zowel met een SPI als een I2C-protocol kan werken. Enkele dagen gezwoegd om het aan de praat te krijgen met een Picaxe, wat voor mij een nieuwe omgeving is. Eens de module aan het werk heb ik het begin van de module beschreven waartoe het dient en welke variabelen er worden gebruikt.
Dat deed ik ook voor een MCP23017 die ook met I2C werkt en het spaart me heel wat werk doordat ik niets meer hoef uit te pluizen en gewoon moet kopiëren.
Dat kopiëren is weliswaar zorgen dat de initialisatie en declareren van de variabelen op de juiste plaats in het programma wordt gedaan en het eigenlijk programma komt dan in een subroutine.

Depeet
Lambiek

Special Member

Op 18 augustus 2019 09:03:11 schreef MGP:
Ik schrijf per project alle denkbare gegevens op papier, krabbels, tekeningen, gebruikte formules enz.. het is een wirwar van gegevens en alles door elkaar en soms ook wel copies van aansluitgegevens ook al staan die op de computer.

Dan kunnen we elkaar de hand geven. Ik doe het op de zelfde manier, zo'n blaadje ziet er niet uit voor een ander, maar het werkt wel.

Als je haar maar goed zit, GROETEN LAMBIEK.

We zouden samen eens een halfgeleidergids moeten maken :) want jij kunt ook nog goed documenten maken en daar heb ik een hekel aan.

LDmicro user.
High met Henk

Special Member

@REW: ik liep tegen hetzelfde probleem aan: het wordt een soort pseudo code, omdat je er geen echte logica aan mee kan geven..

Het is gewoon van onder naar boven het commentaar lezen en opsommen (okee, das erg kort door de bocht, maar wel de basis)

maar het is een IDEE. Het forceert je iig wel commentaar mee te nemen (wat op zich al een goede eigenschap is)

to all newbies: RTFM/D of google eens (p.s. RTFM/D = Read the f*cking manual/datasheet).
Lambiek

Special Member

Op 19 augustus 2019 11:57:15 schreef MGP:
We zouden samen eens een halfgeleidergids moeten maken :)

Wie weet. :)

Als je haar maar goed zit, GROETEN LAMBIEK.

Op 19 augustus 2019 08:51:48 schreef rew:

code:


#define SD_PARITY_ERROR         (eventflags_t)32    /**< @brief Parity.     */

Wat heb ik aan het commentaar dat dit constantes zijn? waar worden ze gebruikt? Wat heb ik aan de documentatie "Parity." bij de constante "SD_PARITY_ERROR". De code geeft in ieder geval aan dat het een ERROR betreft.

Dit is ook geen documentatie van de C-code, maar code voor de doxygen-compiler om een document te maken waarin staat dat SD_PARITY_ERROR de naam is van de constante die een parity error aangeeft.

Dat is voor mensen die programmeren op basis van de documentatie, en die niet in de header files kijken. Want die zijn onleesbaar :-)

Onderliggende probleem is natuurlijk dat Doxygen net zo dom is als de C compiler, en dus net zulke onleesbare input nodig heeft als de C-compiler. En totdat AI werkelijk van de grond komt zal dat probleem voor alle tools gelden die software begrijpelijker/toegankelijker/onderhoudbaarder moeten maken.

Op 20 augustus 2019 14:14:23 schreef blurp:
Dat is voor mensen die programmeren op basis van de documentatie, en die niet in de header files kijken. Want die zijn onleesbaar :-)

In welk universum voegt 'Parity' iets toe aan de documentatie van de constante met PARITY als deel?

"The following constants define the bit flags for various error conditions in the status register ISR of the uart peripheral"

/daar/ heb je wat aan.

four NANDS do make a NOR . Kijk ook eens in onze shop: http://www.bitwizard.nl/shop/

MGP, Lambiek.
Dacht dat ik 1 van de weinige was die eerst op papier wat nadenkt en schetst.
Vooral schema's dan.
Meteen vanuit een PC werken kost me ook moeite.
Zou dit een leeftijds dingetje zijn ?

Lambiek

Special Member

Op 21 augustus 2019 08:59:42 schreef HD13:
Dacht dat ik 1 van de weinige was die eerst op papier wat nadenkt en schetst.

Het is gewoon makkelijk en veel overzichtelijker. En je komt er ook snel achter of iets kan of niet.

Vooral schema's dan.

Schema's doe ik hele kleine stukjes van, dat is weer makkelijk bij het ontwerpen van een print.

Meteen vanuit een PC werken kost me ook moeite.

Het kost me niet echt moeite om het zonder te doen, meestal zit het al in mijn hoofd. Maar als je met meerdere dingen bezig bent is het gewoon makkelijk en hoef je er niet meer bij na te denken.

Zou dit een leeftijds dingetje zijn ?

Ik heb het altijd zo gedaan, ook toen ik jonger was. :)

En dat alles bij elkaar is weer makkelijk voor het schrijven van de software, je snuffelt de aantekeningen even door en het rolt er zo uit. :) Maar eigenlijk is software nooit af, er zijn altijd wel dingen die beter of korter kunnen.

Als je haar maar goed zit, GROETEN LAMBIEK.

Op 21 augustus 2019 08:59:42 schreef HD13:
MGP, Lambiek.
Dacht dat ik 1 van de weinige was die eerst op papier wat nadenkt en schetst.

Hobbymatig is dat meer dan voldoende, professioneel kan dat niet omdat er meestal meerdere personen belang bij hebben dat zoiets correct gedocumenteerd wordt.
Maar idd zoiets op PC verwerken vraagt veel tijd en als je nog een handleiding moet schrijven ben je wel een tijdje zoet.

LDmicro user.
Lambiek

Special Member

Op 21 augustus 2019 09:23:44 schreef MGP:
...., professioneel kan dat niet omdat er meestal meerdere personen belang bij hebben dat zoiets correct gedocumenteerd wordt.

Professioneel kan dat ook prima, dat helpt je weer om te doen wat je hieronder schrijft. :)

Maar idd zoiets op PC verwerken vraagt veel tijd en als je nog een handleiding moet schrijven ben je wel een tijdje zoet.

Als je haar maar goed zit, GROETEN LAMBIEK.

Op 21 augustus 2019 09:09:15 schreef Lambiek:
[...]
Schema's doe ik hele kleine stukjes van, dat is weer makkelijk bij het ontwerpen van een print.

Geinig dat veel technici bijna op dezelfde manier werken. In mijn rugzak die ik naar het werk neem zitten tal van papieren datasheets (fel ingekort met enkel dat wat ik op dat moment belangrijk vind) een notaboekje en vodjes papier, soms zelfs bierviltjes, met wat gekriebel op. Mijn overste krijgt dikwijls kippenvel als hij dat allemaal op mijn bureau ziet liggen :-p
Voor mij zijn het allemaal puzzelstukjes die samen ooit een geheel moeten vormen. En ieder puzzelstukjes probeer ik dan eerst uit of het net dat doet wat ik verwacht. Alles alle stukjes werken, dan pas maak ik er uiteindelijk een schema van, waarna ik dan kan beginnen met een PCB te tekenen.

Laatst ging ik raad vragen aan een collega op een andere dienst. Hij dook meteen in zijn archief, een lade vol met … papiertjes met gekriebel op. Maar hij had wel de oplossing waar ik naar zocht :-p

Depeet
Lambiek

Special Member

Op 21 augustus 2019 09:48:58 schreef depeet:
Voor mij zijn het allemaal puzzelstukjes die samen ooit een geheel moeten vormen. En ieder puzzelstukjes probeer ik dan eerst uit of het net dat doet wat ik verwacht. Alles alle stukjes werken, dan pas maak ik er uiteindelijk een schema van, waarna ik dan kan beginnen met een PCB te tekenen.

Precies. :)

Als je haar maar goed zit, GROETEN LAMBIEK.

Op 21 augustus 2019 05:20:26 schreef rew:
[...]In welk universum voegt 'Parity' iets toe aan de documentatie van de constante met PARITY als deel?

Er moet iets staan in de gegenereerde documentatie.

"The following constants define the bit flags for various error conditions in the status register ISR of the uart peripheral"
/daar/ heb je wat aan.

Nu verwacht je dat er nagedacht wordt. Da's een beginnersfout ;-)

Oef, je vraagt wel iets.

Ten eerste zou ik beginnen met kijken naar TDD(test driven development). Het idee is dat je een test schrijft om je code te testen. Dat kan zelfs gewoon lokaal op je PC. Door voor ieder scenario een test te beschrijven, beschrijf je als het ware meteen wat je code behoort te doen. Dat werkt beter dan documentatie, omdat het automatisch een foutmelding zal geven als je scenario's en je code niet overeen stemmen. Bij ons op de zaak is het credo zelfs "commentaar liegt altijd". Natuurlijk behoeft dat niet het geval te zijn, maar in de praktijk is het erg moeilijk om het allemaal in overeenstemming te houden. En één enkele afwijking trekt in feite al je commentaar in twijfel.

Ten tweede kan je de principes van clean coding aanhouden. Het idee is dat iedere module die je schrijft precies één verantwoordelijkheid heeft. Dat betekent ook dat je heel veel modules zult krijgen, maar dat is overzichtelijker dan een paar hele grote modules.

Bijvoorbeeld een klok. Je zult losse testen schrijven voor het voortschrijden van een seconde, voor de overgang van één minuut, één uur, en één dag. Je schrijft testen voor het instellen van de tijd, het instellen van een alarm, en het verwijderen van een alarm. Je schrijft dan ook een test voor het verwijderen van een alarm als het op snooze staat. Je tijd beheer is een aparte module van je alarm module. Je alarm module een andere dan je snooze module. Je visualisatie weer een andere, je interface naar de hardware of het OS voor het ophalen van de tijd weer een andere.

Meep! Meep!
NarwhalLeo

Special Member

Bij het overzichtelijk houden van code komt vaak een stukje code architechteur kijken. Echt tools zijn er zover ik weet niet...

Aantal tips zijn al gegeven zoals in lagen opbouwen, abstracties maken enz. Twee 'tools' die ik verder nog aan kan bevelen zijn UML voor het modeleren (uittekenen) van de software in een abstracte vorm. Youtube staat vol met informatie hierover.

Een tweede is het gebruik van code patterns. Zeker met embedded raad ik je aan om eens naar een finite state machine te kijken. Dit is een hele interessante architechtuur die super veel gebruikt wordt. Ik denk dat zo'n beetje al je witgoed apparaten draaien op een vorm van een FSM.