Ist es normal / akzeptabel, während der Codierung und Wartung Notizen, Gedanken, Algorithmen und Entscheidungen aufzuschreiben? [geschlossen]

22

Manche Menschen haben das Problem, dass sie nicht ohne Worte denken können. Das Aufschreiben ihrer Gedanken und Entscheidungen ist der effektivste Weg, um fortzufahren.

Ist es normal und akzeptabel, dass ich meine Gedanken und Entscheidungen während des Codierens in eine Notepad ++ - Datei schreibe?

Manchmal sollte es akzeptabel sein, z. B. bei der Neuerstellung von technischer Dokumentation oder beim Nachdenken über komplexere Algorithmen, manchmal kann es jedoch auch merkwürdig sein, z.

Die Auswirkungen dieser Praxis auf die Produktivität sind unklar. Von der einen Seite - das Denken mit inneren Wörtern kann schneller sein als mit den geschriebenen Wörtern. Von der anderen Seite - komplexere Probleme erfordern das Schreiben. Wenn man mehr Gestaltungsmöglichkeiten hat, ist das Gefühl außerdem besser, wenn die Entscheidung geschrieben wird, sodass die Moral steigt.

An Herrn
quelle
5
Ich mache das auch und bereue es im Allgemeinen, wenn ich es nicht tue. Es ist sehr hilfreich, später einen Rückblick zu haben, um sich zu erinnern, warum Sie etwas auf eine bestimmte Weise getan haben, oder um später eine Entscheidung treffen zu können, wenn Sie nicht mit Tunnelblick in der Tiefe sind. Wenn ich vergesse, etwas aufzuschreiben, vergesse ich normalerweise, warum und verbringe dann mehr Zeit damit, meine Schritte zurückzuverfolgen.
PseudoPsyche
21
Ich habe das Gefühl, wir vermissen einen Teil des Kontexts? Wurde diese Beobachtung im Zusammenhang mit einer Beschwerde über die Effizienz gemacht? Oft wird Kritik mit Vorschlägen für die Ursache geäußert, die möglicherweise relevant oder nicht relevant sind.
Jim Rush
9
"Kommentare und Dokumentation" muss in den Quellcode geschrieben und aufbewahrt werden. Ihre Gedanken über die Berücksichtigung von Entwurfsoptionen sind möglicherweise aufgeschrieben, werden jedoch in der Regel nicht aufbewahrt. Diese Informationen werden Ihnen später selten weiterhelfen (Sie können sich Notizen über die Ergebnisse dieses Denkprozesses machen, wenn dies nicht aus dem Quellcode selbst hervorgeht, aber danach hast du nicht gefragt). Wenn Sie ein elektronisches Formular bevorzugen, ein Stift-Papier-Formular oder alles in Ihrem Kopf können, liegt es an Ihnen, niemand anderes, aber Sie können Ihnen sagen, was für Sie am besten funktioniert.
Doc Brown
4
... PS: Normalerweise bevorzuge ich Bleistift und Papier oder eine weiße Tafel für dieses Zeug, und ich denke, ich würde kein besserer Programmierer werden, wenn ich versuchen würde, dies alles in meinem Kopf zu tun, ganz im Gegenteil.
Doc Brown
7
Warum wäre es nicht akzeptabel? Akzeptabel für wen?
Paul D. Waite

Antworten:

62

Das ist nicht nur normal, es ist auch eine gute Idee.

Es gibt ein berühmtes Zitat

"Gib mir sechs Stunden, um einen Baum zu fällen, und ich werde die ersten vier Stunden damit verbringen, die Axt zu schärfen".

Nehmen Sie sich Zeit, um Ihre Gedanken zu organisieren und Ihre Arbeit zu planen, bevor Sie mit dem Programmieren beginnen. Wenn Sie diese Gedanken auf Papier bringen, haben Sie Zeit, über Ihre Pläne nachzudenken, sie zu kritisieren und so zu organisieren, wie es nur "in Ihrem Kopf" schwierig wäre.

Dan Pichelman
quelle
8
Es ist ein gutes Zitat, obwohl ich die falsche Zuschreibung entfernen würde. quoteinvestigator.com/tag/abraham-lincoln
Paul Draper
1
Sicherlich eine wahre Aussage und ein gutes Zitat, aber nach meinem Verständnis hat die Frage einen anderen Schwerpunkt. Soweit ich weiß, hat das OP keine Zweifel daran, wie wichtig es ist, im Voraus zu planen. Er fragt, ob es effizienter ist, diese Gedanken / Planungen aufzuschreiben oder sie alle nur im Kopf zu behalten.
Doc Brown
2
Eine Stunde Schärfen ist mehr als ausreichend. Diese Aufgabe sollte auf maximal 3 Stunden geschätzt worden sein, aber die Pause wurde für sinnlose Übervorbereitung ausgegeben. Was war die Moral nochmal? ;-)
Steve Jessop
26

Ja, das ist völlig akzeptabel und normal.

Die Dokumentation Ihres Entscheidungsprozesses ist oft hilfreich, wenn Sie den Code überarbeiten, um festzustellen, warum der Code auf eine bestimmte Weise geschrieben wurde.

Diese Notizen können als Kommentare direkt in den Code eingefügt werden, wenn sie kurz genug sind. Erweiterte Kommentare werden häufig als Teil eines externen technischen Konstruktionsdokuments aufbewahrt.

mcknz
quelle
4
Ich würde nachdrücklich empfehlen, keine Anmerkungen zur Berücksichtigung von Designoptionen und zum Versuch, ein Urteil als Kommentar im Quellcode abzugeben, aufzunehmen. Diese sind niemals "kurz genug". Nur die endgültigen Ergebnisse dieses Denkprozesses, aber das ist ganz anders, als es das OP verlangt hat.
Doc Brown
3
Ich finde mich oft in Diskussionen wie "Warum haben wir diese Entscheidung getroffen?" Wieder. Es ist unglaublich hilfreich, zu meinen täglichen Projektnotizen zurückzukehren, um den Kontext darzustellen, einschließlich der von uns diskutierten Alternativen. Ich glaube, ich bin in guter Gesellschaft: Laut The Everything Store macht Jeff Bezos dasselbe.
kdgregory
8
@DocBrown - manchmal ist es eine gute Idee ist Gründe sind , warum Sie haben nicht andere mögliche Methoden / Algorithmen verwenden , um ein zukünftiger Entwickler nicht zu ersetzen versuchen , was du getan hast
HorusKol
1
@ HorusKol: sicher, in einigen seltenen Fällen ist das trivialer gesunder Menschenverstand. Das ist aber etwas anderes als "den Entscheidungsprozess zu dokumentieren" .
Doc Brown
1
@DocBrown richtig, ich glaube nicht, dass irgendjemand Seiten mit Notizen in seinem Quellcode haben möchte. :)
McKnz
20

Das ist eine verdammt gute Idee. Bis es zu einem Mittel zum Aufschieben wird.

Der Schlüssel ist das Gleichgewicht. Ich finde, ich bin am produktivsten, wenn ich mich nicht einpacke, sondern Ideen festhalte, wie sie kommen.

Wenn ich auf niedrigem Niveau schleife und eine Idee auf hohem Niveau kommt, schreibe ich sie einfach auf und komme später darauf zurück.

Das Planen von Arbeiten ist eine gute Idee, aber wenn Sie nicht vor Publikum kommunizieren oder präsentieren müssen, sind Stift und Serviette die besten Werkzeuge. Erfassen Sie die Idee. Verschwenden Sie keine Zeit damit, es hübsch zu machen.

kandierte_orange
quelle
Markdown ist ein weiterer guter Weg, um diese Notizen zu machen. Hält Ihre Hände auf der Tastatur, sodass der Denkprozess nur minimal gestört wird.
RubberDuck
1
Ob Sie einen Editor starten oder sich einen Stift und eine Serviette schnappen, hängt ganz von Ihren persönlichen Fähigkeiten im Tippen und Schreiben ab. Die bessere Lösung ist für mich eindeutig der Editor.
cmaster
9

In jeder beruflichen Situation ist dies nicht nur "normal und akzeptabel", sondern auch obligatorisch. Der typische Entwicklungszyklus besteht aus zwei Dokumentationsphasen, bevor die Codierung überhaupt beginnt:

  1. Dokument mit den funktionalen Anforderungen: Dieses Dokument wird in der Regel von Geschäftsanalysten erstellt und gibt die zu implementierende Funktionalität an.

  2. Detail Design Document: Das ist so ziemlich das, worüber Sie sprechen, nur formeller, indem Sie die funktionale Zerlegung (Faktorisierung) des Systems, Algorithmen usw. spezifizieren. Einige meiner (sehr) alten sind online, z . B. diese .

Für weniger formelle Dokumentation stimme ich 110% mit vorhergehenden Anmerkungen zu Inline-Kommentaren überein. Das ist der einzige Weg; So oder so, alles andere geht irgendwann verloren. Ordentliches und durchdachtes Inline-Kommentieren ist jedoch eine eigene Codierungsfertigkeit, die wie jede andere Fertigkeit durch Anstrengung und Übung entwickelt wurde. Sie können einige meiner (sehr) alten Sachen unter sehen, zB dies . Dieser Stil könnte Sie ansprechen oder auch nicht. Ich würde empfehlen, zuerst einen gut kommentierten Code mit einem von Ihnen gewünschten Stil zu finden und diesen in Ihrem eigenen Code zu emulieren. Nach einer Weile passen Sie es an, wie Sie es für richtig halten.

John Forkosh
quelle
4

Ein großartiger Ort, um diese Art von Informationen zu platzieren, ist direkt in der Commit-Nachricht Ihres Versionskontrollsystems (SVN, Git usw.). Auf diese Weise können Sie die Änderungen und die Gründe für sie an derselben Stelle sehen.

Derek
quelle
1
Es macht sie auch durchsuchbar. Sie können Commit-Nachrichten in git und sourcetree in der Befehlszeile suchen, z. B. Wenn Sie nur den Editor verwenden, werden die Dateien höchstwahrscheinlich nie wieder geöffnet und können nur schwer durchsucht werden, wenn Sie etwas ausführliches Bash kennen und ein Skript schreiben, das alle relevanten Stellen durchsucht.
Hoffentlich
Ich versuche dies sowohl in meinen Festschreibungsanweisungen als auch in der Fehler- oder Funktionsanforderung mit Links zum Festschreiben zu tun. Ich habe auch Inline-Kommentare im Code mit Gründen datiert, warum ich den Code geändert habe. Dies hilft dramatisch in unserer knarrenden alten Codebasis, in der Kommentare weitgehend unbekannt sind.
Delliottg
Nein, das ist etwas anderes. Commit-Nachrichten sollten beschreiben, was und nicht warum getan wurde. Das Warum wird in Ihren Dokumentationscodekommentaren, der Begleitdokumentation und der Problemverfolgungslösung angegeben. Sie können nicht fünf Seiten Notizen und Design-Arbeit in eine Commit-Nachricht einfügen, und Sie sollten auch nicht wollen.
Leichtigkeit Rennen mit Monica
Es ist großartig, es in das Versionskontrollsystem zu integrieren. Ein besserer Ort ist jedoch eine reine Textdatei. Diese sind einfacher zu verwenden als Commit-Nachrichten.
Thorbjørn Ravn Andersen
2

Zusätzlich zu den anderen guten Antworten füge ich hinzu, dass ich oft meine Gedanken darüber aufschreibe, was ich versuche zu tun.

Wenn ich sehr explizit artikuliere, was ich versuche, kann ich Vermutungen, Annahmen und / oder Anforderungen realisieren, die nicht unbedingt zutreffen.

Das deutet dann auf Alternativen hin, über die ich dann jeweils besser nachdenken kann; Dieses Schreiben hilft mir, meinen Platz zu retten, wenn ich an etwas anderes denke.

Ich mache mir schnelle Notizen, um Atem und Tiefe zu erkunden, so dass es rekursiv funktioniert und mir dabei hilft, einen Lösungsbaum zu erarbeiten, zu navigieren und zu bewerten, zu sichern, zu erforschen, zu entdecken, zu realisieren und zu entscheiden.

Erik Eidt
quelle
1

Alles aufzuschreiben, was Ihnen / (neuen) Teammitgliedern Zeit ersparen kann, ist Zeit, die Sie sinnvoll einsetzen müssen. Stellen Sie nur sicher, dass es sich um etwas handelt, das jemand später benötigt, und überdenken Sie nicht, es sei denn, es handelt sich um ein wirklich langfristiges Projekt.

Es sollte auch keine Zeit in Anspruch nehmen. Wenn Sie Zeit zum Nachdenken haben, können Sie Ihre Gedanken 1 zu 1 aufschreiben (solange sie jemandem nützlich sein können).

Das eigentliche Problem könnte darin bestehen, zu überdenken, was Sie schreiben. Nur weil Sie schreiben, müssen Sie sich nicht an ein bereits vorhandenes Format halten oder eine vollständige Dokumentation erstellen.

Wenn Sie wählen, ob Sie nichts aufschreiben oder nur unformale Notizen auf einen Notizblock schreiben möchten, schreiben Sie einfach unformale Notizen.

Hoffentlich hilfreich
quelle
1

Sie sagen: "Manche Menschen haben das Problem, dass sie nicht ohne Worte denken können. Das Aufschreiben ihrer Gedanken und Entscheidungen ist der effektivste Weg, um fortzufahren."

Wenn es am effektivsten ist, Ihre Gedanken und Entscheidungen aufzuschreiben, warum wäre es dann nicht normal und akzeptabel, so effektiv wie möglich vorzugehen? Sie tun, was für Sie am besten funktioniert. Es ist möglicherweise nicht das, was für jemand anderen am besten funktioniert. In diesem Fall lässt du dich nicht von jemand anderem sagen, was für dich am besten ist, und du sagst ihm nicht, was für ihn am besten ist. Jeder tut, was für ihn am besten ist.

gnasher729
quelle
1

Der Mensch kann nur sieben "Dinge" gleichzeitig im Kopf haben. Das ist der Grund für siebenstellige Telefonnummern. Damit Programmierer effizient arbeiten können, müssen sie eine Art System finden, um Dinge aus ihrem Speicher zu entfernen und sie später bei Bedarf schnell abzurufen. Ihre Notizen sind ein offensichtlicher und direkter Weg, aber jeder, der an etwas mäßig Komplexem arbeitet, muss es irgendwie tun . Wenn Sie ein Programm mit jemandem koppeln, achten Sie unbedingt auf dessen Methode.

Ein gängiger Weg ist die testgetriebene Entwicklung. In dieser Methodik schreiben Sie einen fehlgeschlagenen Test, Sie schreiben gerade genug Code, um diesen fehlgeschlagenen Test zu bestehen, und Sie überarbeiten Ihren Code, damit er besser aussieht, während Sie alle vorhandenen Tests bestehen. Bei dieser Methode bleiben alle Ihre "Notizen" in den Tests verschlüsselt. Menschen können auf diese Weise sehr schnell arbeiten, ohne sich Notizen zu machen, weil sie sich nur auf den nächsten Test konzentrieren.

Eine andere gebräuchliche Methode besteht darin, Ihre Notizen einfach als Pseudocode-Kommentare oder -Stubs in Ihren Code zu schreiben und sie dann nach und nach durch das Original zu ersetzen. So schreibe ich normalerweise Algorithmen. Mein erster Entwurf ist nur eine Hauptfunktion mit Pseudocode, die sich dann nach und nach in immer tieferen Abstraktionsebenen ausfüllt.

Fühlen Sie sich nicht schlecht, wenn Sie eine Methode verwenden, die für Sie funktioniert, aber versuchen Sie festzustellen, welche Methoden Ihre "effizienten" Kollegen verwenden. Sie haben die gleichen menschlichen Einschränkungen, die Sie tun.

Karl Bielefeldt
quelle
1
TDD ist eine Notizübung? Ich glaube nicht.
Robert Harvey