# Hi Leuts,
ich verwende gerne H-File- und C-File_Templates, um den genannten Files
etwas Struktur zu verleihen. Jetzt wollte ich euch mal fragen:
- Benutzt ihr auch so was?
- Was haltet ihr von meinen Templates? Sind sie übersichtlich oder gar
überladen? Sind sie zu detailiert oder zu wenig detailiert? ...
- Bin offen für Verbesserungsvorschläge und vlt. hat der ein oder andere
noch eine sehr gute Vorlage. Vielleicht bin ich auch der einzige der
glaubt, dass die Templates gut zu iwas sind. Ich lasse mich mal
überraschen.
## C-File
Oliver S. schrieb:> Man könnte zumindest drüber diskutieren, was private Daten und> Funktionen in einem Header zu suchen haben.
Hat er ja nicht.
Ja, man kann sowas machen. Hat natürlich insbesondere Sinn, wenn man ein
automatisches System hat, was nach bestimmten Dingen sucht, bspw. wenn
mit Doxygen hinterher eine Doku gebaut werden soll.
@Last_editor und @Last_change sind aber sinnlos in der Datei. Das sind
Metadaten, für deren Verwaltung das VCS da ist. Ob @Version irgendwie
sinnvoll ist, musst du in deinem Kontext selbst wissen, muss ja
schließlich jemand aktiv pflegen.
"Description" schreibt sich mit "p". ;-)
Zudem finde ich diese redundanten Kommentarblöcke absolut bekloppt. Es
liest ja nicht die Sekretärin den Code, sondern jemand, der sich
halbwegs auskennt vulgo Programmierer. Und dann vor einer Folge von
include-directiven einen solchen Kommentar zu schreiben, grenzt an
Körperverletzung.
MaWin schrieb:> Wilhelm M. schrieb:>> Ich finde den End-of-file marker sehr wichtig!>> Leider fehlt der BEGIN OF FILE marker.> Wie soll man sonst Ende und Anfang finden?
Den habe ich glatt nicht gefunden, weil die Markierung fehlte, weswegen
ich nicht gemerkt habe, dass die Markierung fehlt!
Verzichte auf
#ifdef __cplusplus
extern "C" {
#endif
Sondern nimm gleich C++.
In dem Header hast du dann eine
class xxx
{
public:
private:
};
damit ersparst du dir die Sectionen.
Defines kann man sich in C++ ersparen. Da gibt es wunderbare enums und
Konstanten, die nur für Klassen gelten. Ohne Defines gibt es weniger
Fehler.
Dass oben die Includes kommen, muss man nicht extra ankündigen. Das ist
wie Rechtsfahren im Straßenverkehr.
Einzig das würde ich noch machen:
/* @
* @Last_editor :
* @Description :
*/
Und zwar doxygen Style.
Version und Datum kann weg, das übernimmt eh die Versionskontrolle
(SVN/GIT/etc)
PittyJ schrieb:> Verzichte auf>> #ifdef __cplusplus> extern "C" {> #endif>> Sondern nimm gleich C++.
Der Spruch hätte von mir kommen können ;-)
Das macht er ja, sonst hätte er die extern "C" Deklaration nicht
geschrieben
(die include-directiven sollten dann außerhalb der extern-Deklaration
stehen).
Die old-school include-guards kann man durch ein #pragma once ersetzen.
Wilhelm M. schrieb:> Die old-school include-guards kann man durch ein #pragma once ersetzen.
Für portablen Code nicht.
Ich weiß gar nicht, ob sich die WG14 nun darauf einigen konnte, das in
C23 aufzunehmen. Ich glaube mich zu erinnern, dass es dafür keinen
Konsens gab.
> Das macht er ja, sonst hätte er die extern "C" Deklaration nicht> geschrieben
Die schreibt man ja erstmal nur, damit der Header sowohl in C als auch
C++ einbindbar ist.
Jörg W. schrieb:> Wilhelm M. schrieb:>> Die old-school include-guards kann man durch ein #pragma once ersetzen.>> Für portablen Code nicht.
In der Theorie ja, in der Praxis nein.
s.a.:
https://en.wikipedia.org/wiki/Pragma_once#Portability>> Das macht er ja, sonst hätte er die extern "C" Deklaration nicht>> geschrieben>> Die schreibt man ja erstmal nur, damit der Header sowohl in C als auch> C++ einbindbar ist.
Schrieb ich ja.
Sooo...
Erstmal vielen Dank für das Feedback. Ich gebe euch recht, es an doxygen
anzupassen macht sehr viel Sinn. Ich verstehe nicht ganz warum man sich
dagegen sträubt einen dedizierten Bereich für includes vorzusehen.
Schadet ja nicht wirklich, oder nicht?
Genauso sehe ich das mit "end of file" und "begin of file" schadet
erstmal nicht. Ist meiner Meinung nach ästhetisch ansprechender und
übersichtlicher.
Naja ist wahrscheinlich beides Ansichtssache... :)
Auch die Kritik mit der Versionkontrolle ist absolut berechtigt.
Normalerweise ist das in Git alles bereits vermerkt. Insofern benötigt
es nicht mal einen @author, da der in der Regel den Code ja auch
hochläd, oder nicht??? Macht vlt. trotzdem Sinn an jeder Funktion den
letzten Autor zu vermerken, ist ja nicht immer soooo eindeutig an
welchen Stellen genau etwas seit dem letzten Master (Git) geändert
wurde.
Naja lange Rede kurzer Sinn! Hier sind meine angepassten Templates:
c-file
* Write here in detail explanation what function does.
7
*
8
* @author write here your name
9
*
10
* @param explain what the parameters do (are used for)
11
*
12
* @return write what the return value does (is used for)
13
*
14
* @pre write down what is necessary to befor call this function
15
* @example write down a little example if helpfull/necessary
16
*/
17
intfoo(
18
parameter_x,
19
paramete_z
20
);
21
22
//c-file: how does the function do this
23
24
/**
25
* @details In detail explanation of a part of the function how it does this.
26
*
27
* @todo write down what is todo with this function
28
* @bug write down discovered bugs
29
* @test write down what is untested
30
*/
31
intfoo(
32
parameter_x,
33
paramete_z
34
);
Ich bin mir jedoch nicht wirklich sicher ob auch bspw. enum, variablen,
structs usw. auch jeweils eine doxygen docu benötigen. Mir geht es hier
nicht nur um API-Documenatation sondern auch darum, dass andere mit
meinem Code gut arbeiten können, er lesbar wartbar und verständlich ist.
Also was haltet ihr von so einem kleinen Header vor eben solchen
"Objekten".
Aabeku K. schrieb:> Macht vlt. trotzdem Sinn an jeder Funktion den> letzten Autor zu vermerken, ist ja nicht immer soooo eindeutig an> welchen Stellen genau etwas seit dem letzten Master (Git) geändert> wurde.
Natürlich ist das eindeutig!
Und alles, was zu Fuß gemacht werden soll, unterbleibt bzw. ist eine
Fehlerquelle.
Aabeku K. schrieb:> Mir geht es hier> nicht nur um API-Documenatation sondern auch darum, dass andere mit> meinem Code gut arbeiten können, er lesbar wartbar und verständlich ist.
Ein wichtiger Grundsatz lautet:
Kommentiere nur das, was der Code nicht sagen kann, und nicht das, was
der Code nicht sagt!
Aabeku K. schrieb:> Macht vlt. trotzdem Sinn an jeder Funktion den letzten Autor zu> vermerken, ist ja nicht immer soooo eindeutig an welchen Stellen genau> etwas seit dem letzten Master (Git) geändert wurde.
Meine Erfahrung: diese Angaben im Header einer Datei sind nach der
ersten Erstellung grundsätzlich out of date. Daher weglassen und bei
Bedarf im VCS nachschauen.
Wilhelm M. schrieb:> Zudem finde ich diese redundanten Kommentarblöcke absolut bekloppt.
Da schließe ich mich uneingeschränkt an.
Code, der so etwas nutzt, stammt entweder aus maschineller Erzeugung,
oder aus einem Umfeld, in dem das zwingend gefordert wird, oder von ...
fachfremden. Im letzteren Fall ist dann leider auch das, was folgt,
wenig interessant.
Aber wie bei allen Stylefragen in diesem Kontext hier gibt es weder ein
falsch oder richtig, noch einen Einigung.
Darf jeder machen, wie er will.
Oliver
Abgesehen von den include guards haben meine .h Files nichts gemeinsam.
Ich nutze keine solchen Templates, lohnt sich nicht. Auch extern "C"
mach ich nicht. Meine C-Header sind sowieso oft inkompatibel mit C++.
"begin of file" und "end of file" ist völlig Wert-frei - das sieht jetzt
schön homogen aus - aber wenn da funktionen drin sind usw. macht das
absolut keinen sinn mehr, der Anfang ist begin und das Ende ist end -
warum das noch zusätzlich sagen - nur damits gemacht ist?
*@file header name
ist auch fraglich, wenn du dann mal aufräumen willst musst du zusätzlich
zu dem Dateinamen und Makefiles etc. noch in den Header diese
Micro-Details ändern - das wird kaum jemand aktiv pflegen
*@author write here your name
genau so fraglich - das macht nur Sinn wenn es 3 Entwickler gibt die
immer nur ihren Kram machen - wenn du da 10 Leute dran hast ist das in
wenigen Tagen ohne Wert weil der 1. hat nicht die Änderungen vom letzten
Verstanden usw. - git reicht da mehr als völlig
allgemein ist diese ASCII-Animations-Orgien in Source-Code mehr oder
minder so stark wie möglich zu vermeiden - sowas kenn ich immer nur von
alten Projekten oder Studentenaufgaben weil die Profs denken das wäre
professionell
am liebsten sind mir dann private Functions und Konstanten im Header
deklariert - das macht das ganzen dann noch mal ordentlich sinnfreier -
aber das hast du zum Glück ja gleich gefixt
Aabeku K. schrieb:> //------------------------------------- ... ----------------------//> //end of file-------------------------- ... ----------------------//> //------------------------------------- ... ----------------------//
Gerüchten zufolge will die EU auch eine Kennzeichnungspflicht für
Wurstenden einführen, damit niemand versehentlich darüber hinaus isst :)
Ich glaube, ich würde das ohne klappbare Regions als Balast empfinden.
Und auch mit Regions ordne/sortiere/schreibe/suche ich den Code eher
inhaltlich als formal.
Aber ich bin da auch Schmuddelkind.
Das meiste wird schon du VCS erschlagen und somit nicht nötig.
* Wie sieht es mit Lizenzbestimmungen und Copyright aus?
* Falls C++ darf ich auch inline code schreiben im Header?
Wilhelm M. schrieb:> Ein wichtiger Grundsatz lautet:> Kommentiere nur das, was der Code nicht sagen kann, und nicht das, was> der Code nicht sagt!
Da sind 2 Negierungen drin!
Das Stammhirn tut sich schwer mit Negierungen, es ist älter als das
Konzept Negierung.
Ein wichtiger Grundsatz lautet:
> Der Code zeigt was getan wird.> Der Kommentar sagt, warum es so getan wird.
Knuth war wohl der letzte, der bei einem Glas Rotwein eine Quelltext wie
Literatur gelesen hat.
Heute browsed man da eher mit seinem Editor durch und freut sich über
jeden Kommentar, über den man nicht lange hinwegscrollen muss.
Selbst in einem Buch erwartet man nicht, dass der Setzer Hinweise gibt,
wo die Einleitung anfängt, aufhört und dass der Fettgedruckte Text ein
Kapitel beginnt
Das äquivalent zum Fettdruck macht Dein Editor.
Also ja, mache es wie Du möchtest, aber sei Dir bewusst, dass weniger
mehr ist. Es ist eher etwas, was Deine Kollegen tolerieren und
verzeihen.
Hier noch eine Anmerkung zum Thema End-Of-File Marker aus der Praxis,
ist aber schon paar Jahre her:
1
// file a.h
2
...diverserCodehier...
3
//--- END OF FILE --- (<-- Hier Dateiende OHNE CR-LF!)
Aufruf dann in f.c:
1
lines...
2
line101:#include"a.h"
3
line102:#include"b.h"
4
line103:#include"c.h"
Manch alter Compiler (Stand 2010!) hat im Preprozessor die Datei a.h
expandiert Zeile für Zeile. Am Dateiende dann aber mangels Zeilenende
gilt der '//' Comment bis zum nächsten zeilen-Ende, so wie beim
Line-continuation '\' am Zeilenende wird die nächste Zeile mit aktuellen
zu einer gmacht, wegen Comment-Start aber auch nur als Comment-Text.
Somit landet das #include "b.h" als vermeintlicher Kommentar im Nirwana.
Gilt aber auch für jeglichen anderen Code in der Zeile
Ist mir damals tatsächlich passiert, mit einem kommerziellen Compiler
(war nicht gcc).
Da man je nach Editor-Einstellung ein fehlendes abschliessendes CR am
Dateiende nicht sieht, habe ich mir angewöhnt den /** END file.h ****/
IMMER als klassischen C-Comment zu tippen, niemals im C++ Style.
Aktuelle Compiler sollten allerding hier eine Warning ausgeben, einfach
mal ausprobieren.
Reinhold_by schrieb:> Ist mir damals tatsächlich passiert, mit einem kommerziellen Compiler> (war nicht gcc).
Der hat auch völlig recht.
Obwohl C sich an sich nicht um Zeilenenden kümmert, das Preprocessing
ist tatsächlich zeilenweise definiert (was angesichts von Dingen wie
#ifdef oder #define auch Sinn hat), und eine Zeile endet nun einmal mit
einem Zeilenendezeichen.
cppbert schrieb:> *@file header name> ist auch fraglich
Ist halt eine mögliche Direktive für Doxygen. Wenn man wirklich mal
Dateien umbenennt, muss man das natürlich im Blick haben. Aber
Umbenennen ist in einem VCS eh immer so eine Sache, haben wir bislang
vermieden, wenn es geht.
Jörg W. schrieb:> Aber Umbenennen ist in einem VCS eh immer so eine Sache, haben wir> bislang vermieden, wenn es geht.
Ich habs noch nie vermieden, wenn ein Projekt wächst kann die bestehende
Benennung/Struktur nicht mehr passen, erst letzte Woche eine Lib in
viele Teil Libs zerlegt und Namen,Classen angepasst... nach dem sie von
<50 Dateien auf >300 gewachsen war
EAF schrieb:> Da sind 2 Negierungen drin!> Das Stammhirn tut sich schwer mit Negierungen, es ist älter als das> Konzept Negierung.
Das ist ein Zitat, deswegen steht es in dieser Form da.
Und diese Form ist m.E. auch die Richtige trotz der doppelten
Verneinung, denn die Aufforderung, die in diesem Satz steckt, entdeckt
man vvlt auch erst durch etwas Nachdenken ...
Reinhold_by schrieb:> Aktuelle Compiler sollten allerding hier eine Warning ausgeben, einfach> mal ausprobieren.
Ein Source-Datei ohne Zeilenende am Ende der Datei ist nicht-wohlgeformt
laut Standard. Aber (fast) jeder Quelltexteditor fügt das automatisch
hinzu.
Jörg W. schrieb:> Obwohl C sich an sich nicht um Zeilenenden kümmert, das Preprocessing> ist tatsächlich zeilenweise definiert (was angesichts von Dingen wie> #ifdef oder #define auch Sinn hat), und eine Zeile endet nun einmal mit> einem Zeilenendezeichen.
Laut Standard muss eine Quelltextdatei mit einem Zeilenende enden, steht
im Standard.
Jörg W. schrieb:> Aber> Umbenennen ist in einem VCS eh immer so eine Sache, haben wir bislang> vermieden, wenn es geht.
Welches veraltete VCS verwendest Du denn?
A. S. schrieb:> Heute browsed man da eher mit seinem Editor durch und freut sich über> jeden Kommentar, über den man nicht lange hinwegscrollen muss.
Normalerweise ernte ich ja immer Spott in diesem Forum, wenn ich sage,
der Code und die Kommentare altern unterschiedlich. Anfänger glauben das
meistens nicht, und müssen erst einmal schön auf die Nase fallen.
Genauso wie Anfänger nicht daran glauben, das Zusicherungen in Form von
Assertionen auch so eine Kommentarfunktion übernehmen (auf unterer
Ebene) bzw. Anfänger glauben ja meist überhaupt nicht, dass
Zusicherungen hilfreich sind.
Daher ist als Handreiche mein schon oben genannten Leitsatz sehr
hilfreich.
Wilhelm M. schrieb:> Jörg W. schrieb:>> Aber>> Umbenennen ist in einem VCS eh immer so eine Sache, haben wir bislang>> vermieden, wenn es geht.>> Welches veraltete VCS verwendest Du denn?
Git. :-)
Das hat, im Gegensatz zu SVN, ja nur guesswork für Umbenennungen, und
dass man nachher irgenwelche Stücken in der History zusammenkramen muss,
ist mir schon mit so ziemlich allen VCSen passiert. War'n schon ein paar
mittlerweile in meinem Leben. ;-)
Wilhelm M. schrieb:> Das ist ein Zitat, deswegen steht es in dieser Form da.
Gibt es das Zitat mit dem zweiten Halbsatz auch irgendwo im Internet
(außer von Dir)? Der erste ist einleuchtend, der zweite
interpretationsbedürftig.
A. S. schrieb:> Wilhelm M. schrieb:>> Das ist ein Zitat, deswegen steht es in dieser Form da.>> Gibt es das Zitat mit dem zweiten Halbsatz auch irgendwo im Internet> (außer von Dir)? Der erste ist einleuchtend, der zweite> interpretationsbedürftig.
Kevlin Henney, "97 things every programmer should know"
A. S. schrieb:> Gibt es das Zitat mit dem zweiten Halbsatz auch irgendwo im Internet> (außer von Dir)? Der erste ist einleuchtend, der zweite> interpretationsbedürftig.
Nicht nur interpretationsbedürftig, sondern sogar widersprüchlich.
Wilhelm M. schrieb:> Kommentiere nur das, was der Code nicht sagen kann, und nicht das, was> der Code nicht sagt!
Was der Code nicht sagen kann, wird er auch nicht sagen.
Soll nun etwas, das der Code nicht sagen kann, kommentiert werden?
Die erste Hälfte des Satzes sagt ja, die zweite nein.
Die Aussage ist also Unsinn, es sei denn, es steckt eine versteckte
Ironie darin, die ich nicht erkannt habe. Ohne das letzte "nicht" würde
ich der Aussage zustimmen.
Wilhelm M. schrieb:> Kevlin Henney, "97 things every programmer should know"
Ah jetzt ja :)
Dann zitier doch wenigstens richtig:
"Comment what the code cannot say, not simply what it does not say."
Das "simply" macht einen kleinen, aber entscheidenden Unterschied.
Yalu X. schrieb:> A. S. schrieb:>> Gibt es das Zitat mit dem zweiten Halbsatz auch irgendwo im Internet>> (außer von Dir)? Der erste ist einleuchtend, der zweite>> interpretationsbedürftig.>> Nicht nur interpretationsbedürftig, sondern sogar widersprüchlich.>> Wilhelm M. schrieb:>> Kommentiere nur das, was der Code nicht sagen kann, und nicht das, was>> der Code nicht sagt!>> Was der Code nicht sagen kann, wird er auch nicht sagen.
Das ist Quatsch!
> Wilhelm M. schrieb:>> Kevlin Henney, "97 things every programmer should know">> Ah jetzt ja :)>> Dann zitier doch wenigstens richtig:>> "Comment what the code cannot say, not simply what it does not say.">> Das "simply" macht einen kleinen, aber entscheidenden Unterschied.
Wenn Du ihn in Vorträgen gehört hättest und Dir auch ein bisschen mehr
Mühe bei der Interpretation gegen würdest, dann würdest Du die Botschaft
erkennen.
Wilhelm M. schrieb:> Yalu X. schrieb:> ...>> Was der Code nicht sagen kann, wird er auch nicht sagen.>> Das ist Quatsch!
Kein Quatsch, denn wenn er es sagen würde, wäre das der deutlichste
Beweis dafür, dass er es auch kann.
Wilhelm M. schrieb:> Wenn Du ihn in Vorträgen gehört hättest und Dir auch ein bisschen mehr> Mühe bei der Interpretation gegen würdest, dann würdest Du die Botschaft> erkennen.
Ich erkenne die Botschaft sehr wohl aus dem Originalzitat, nicht aber
aus deinem misslungenen Versuch, es ins Deutsche zu übersetzen.
Schreib beim nächsten mal bei deinen tollen Sprüchen doch einfach mit
dazu, woher sie kommen (was generell guter Stil ist) und wie sie im
Original lauten. Das hilft, solche Missverständnisse zu vermeiden.
Yalu X. schrieb:> Wilhelm M. schrieb:>> Yalu X. schrieb:>> ...>>> Was der Code nicht sagen kann, wird er auch nicht sagen.>>>> Das ist Quatsch!>> Kein Quatsch, denn wenn er es sagen würde, wäre das der deutlichste> Beweis dafür, dass er es auch kann.
Leider hast Du es immer noch nicht verstanden. Kommentare solle nur das
sagen, was der Code (nicht sagt und nicht) sagen kann. Darauf liegt die
Betonung.
Und es entsteht daraus eine ganz klare Handlungsanweisung. Und das ist
das Wichtigte an dem Satz: der Code soll solange refaktoriert werden,
bis er ganz klar das sagt, was er tut.
Und das steht in dem Artikel in dem Buch drin. Du solltest das dann auch
hier sagen und nicht den Quatsch von oben.
Wilhelm M. schrieb:> Leider hast Du es immer noch nicht verstanden.
Doch, ich habe Henneys Aussage sogar sehr gut verstanden und auch die
darin implizit enthaltene Handlungsanweisung herausgelesen, den Code
möglichst selbsterklärend zu schreiben, um den Umfang der notwendigen
Kommentare auf ein Minimum zu reduzieren. Ich stimme der Aussage auch zu
100% zu.
Ich habe sie aber nur in ihrer englischen Originalformulierung
verstanden und nicht in deiner Übersetzung. Hättest du das "simply" (in
diesem Kontext "einfach") nicht unterschlagen, wären mir schon früher
die Augen geöffnet worden.
Noch klarer wäre die Aussage gewesen, wenn du wenigstens noch ein oder
zwei Sätze Kontext aus Henneys Artikel mitgeliefert hättest.
Du hast den Satz aber einfach aus dem Kontext gerissen und zudem noch
unvollständig übersetzt. Beides in Kombination führt unweigerlich zu
Missverständnissen. Das ging ja offensichtlich nicht nur mir so.
Aber sei's drum. Mittlerweile sind die Missverständnisse ja ausgeräumt.
Aabeku K. schrieb:> Insofern benötigt> es nicht mal einen @author, da der in der Regel den Code ja auch> hochläd, oder nicht??? Macht vlt. trotzdem Sinn an jeder Funktion den> letzten Autor zu vermerken, ist ja nicht immer soooo eindeutig an> welchen Stellen genau etwas seit dem letzten Master (Git) geändert> wurde.
Dafür gibt es "git blame".
Da sieht man für jede Code-Zeile, wer sie zuletzt geändert hat und in
welchem Patch. Der Patch hat (hoffentlich) eine gut Beschreibung was
genau geändert wurde, wer beteiligt war (Autor, Reviewer, Ideengeber)
und warum.
Man kann nur nicht so leicht herausfinden, wer eine bestimmte Code-Zeile
die es vor einiger Zeit noch gab gelöscht hat.
Thread beobachten
Seitenaufteilung abschalten