Als «documentation» getaggte Fragen

Viele Leute behaupten, "Kommentare sollten erklären, warum, aber nicht wie". Andere sagen, "Code sollte sich selbst dokumentieren" und Kommentare sollten knapp sein. Robert C. Martin behauptet, dass (in meinen eigenen Worten umformuliert) Kommentare häufig "Entschuldigungen für schlecht...

Ich wurde ausdrücklich gebeten, zeilenweise (oder entsprechend - zum Beispiel Bild für Bild usw.) Erklärungen oder Kommentare abzugeben, die mein Chef lesen und befolgen kann. Da er kein Programmierer ist, kann er dem Code nicht folgen und möchte, dass alles ins Englische übersetzt wird. Wurde...

Der RFC 2606- Standard reserviert die Domänennamen example.org , example.net und example.com, um sie als Beispiele in der Dokumentation zu verwenden. Was entspricht einer Telefonnummer (einschließlich Landesvorwahl), die als Beispiel dienen kann, z. B. um Benutzern ein Beispiel für die Eingabe von...

Angenommen, ich entwickle ein relativ großes Projekt. Ich habe bereits alle meine Klassen und Funktionen mit Doxygen dokumentiert, aber ich hatte die Idee, auf jede Quellcodedatei einen "Programmierer-Hinweis" zu schreiben. Die Idee dahinter ist, in Laienbegriffen zu erklären, wie eine bestimmte...

Während einer Besprechung zum Rollback eines SDK von Drittanbietern aus der neuesten Version wurde festgestellt, dass unsere Entwickler bereits im Festschreibungsverlauf darauf hingewiesen haben, dass die neueste Version nicht verwendet werden sollte. Einige Entwickler argumentierten, dass dies...

Ich arbeite an einem ziemlich großen Projekt und habe die Aufgabe, einige Übersetzungen dafür zu machen. Es gab Unmengen von Etiketten, die nicht übersetzt wurden, und während ich den Code durchsuchte, fand ich dieses kleine Stück Code //TODO translations Dies brachte mich dazu, über den Sinn...

Ich habe folgenden Code geschrieben: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());

Zunächst möchte ich mich in dieser Frage von der Polemik fernhalten, ob das Kommentieren von Quellcode gut oder schlecht ist. Ich versuche nur klarer zu verstehen, was die Leute meinen, wenn sie über Kommentare sprechen, die Ihnen sagen, WARUM, WAS oder WIE. Wir sehen oft Richtlinien wie...

Ich habe vor drei Monaten an einem Projekt gearbeitet, und dann tauchte plötzlich ein anderes dringendes Projekt auf, und ich wurde gebeten, meine Aufmerksamkeit zu verlagern. Ab morgen gehe ich zurück zum alten Projekt. Mir ist klar, dass ich mich nicht daran erinnere, was ich genau getan habe....

Ich plane, meinen aktuellen Job zu verlassen, da wir Blub mit einem Unternehmens-Blub-Framework und einem Blub-Webserver auf mittelmäßigem Shared Hosting verwenden. Meine Mitarbeiter sind freundlich und mein Chef ist ein durchschnittlicher Kleinunternehmer - ich möchte aus technischen Gründen ganz...

Ich verstehe die Bedeutung von gut dokumentiertem Code. Ich verstehe aber auch die Bedeutung von selbstdokumentierendem Code. Je einfacher es ist, eine bestimmte Funktion visuell zu lesen, desto schneller können wir bei der Softwarewartung fortfahren. Vor diesem Hintergrund möchte ich große...

Die automatische Dokumentationserstellung kann mit einer Vielzahl von Werkzeugen durchgeführt werden, wobei GhostDoc eines der bekanntesten ist. Per Definition ist jedoch alles, was es erzeugt, redundant. Es wirft einen Blick auf Namen von Methoden, Klassen, etc. und gibt Englisch , das könnte sie...

Ich schreibe eine Benutzerdokumentation (eine SOP), die Programme von Drittanbietern umfasst, die ich versuche, gut zu beschreiben. Ein solches Programm ist ein Server, der neben einer Grafik, die während seiner Initialisierungs- / Startroutine angezeigt wird, nur wenige Informationen zum Start...

Manchmal finde ich mich in Situationen wieder, in denen der Teil des Codes, den ich schreibe, so selbstverständlich ist (oder zu sein scheint ), dass der Name im Grunde genommen als Kommentar wiederholt wird: class Example { /// <summary> /// The location of the update. /// </summary>...

Wenn Sie Tools wie jsdocs verwenden , werden statische HTML-Dateien und deren Stile in Ihrer Codebasis basierend auf den Kommentaren in Ihrem Code generiert. Sollen diese Dateien in das Git-Repository eingecheckt oder mit .gitignore ignoriert

Eines der Hauptziele von Softwareentwicklungsunternehmen ist die Erhöhung des Busfaktors. Dies wird auch in einem von Google organisierten Vortrag befürwortet . Das bedeutet, dass Sie alles so codieren und dokumentieren sollten, dass das Projekt fortgesetzt werden kann, wenn Sie morgen mit dem Bus...

Es scheint eine Abneigung gegen das Schreiben der grundlegendsten Dokumentation zu geben. Unsere Projekt-READMEs sind relativ einfach. Es gibt nicht einmal aktualisierte Listen von Abhängigkeiten in den Dokumenten. Gibt es etwas, das ich in der Branche nicht kenne, das Programmierer dazu bringt,...

Wenn ich an Code arbeite, stelle ich mich den gleichen Herausforderungen wie meine Teamkollegen, und ich habe einige hilfreiche Funktionen und Klassen geschrieben, und auch diese. Wenn es eine gute Kommunikation gibt, höre ich von etwas Großartigem, das jemand zusammengestellt hat, und sechs Monate...

Ich finde mich (hoffentlich) hilfreiche Kommentare in Code (C ++) Dokumentation des Typs schreiben: The reason we are doing this is... Der Grund, warum ich "wir" anstelle von "ich" benutze, ist, dass ich viel akademisch schreibe, wobei "wir" oft bevorzugt werden. Also hier ist die Frage. Gibt es...

Das CS-Programm meiner Schule vermeidet jede Erwähnung von objektorientierter Programmierung, deshalb habe ich einige Lektüre allein gemacht, um es zu ergänzen - insbesondere die objektorientierte Softwarekonstruktion von Bertrand Meyer. Meyer weist wiederholt darauf hin, dass Klassen möglichst...