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 geschriebenen Code" sind. Meine Frage lautet wie folgt: Was ist falsch daran, einen …

236 programming-practices  documentation  comments 

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 schon jemand dazu aufgefordert? Ich …

155 documentation 

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 Telefonnummern in welchem ​​Format zu geben? Im besten …

112 documentation  standards  help-documentation 

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 Klasse funktioniert (und nicht nur warum, wie die meisten …

104 documentation  large-scale-project 

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 eine schlechte Praxis sei und stattdessen entweder in der Quelldatei (dh // Don't …

94 version-control  documentation 

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 dieser Kommentare für sich …

86 documentation  comments 

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()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Hier steht eine auskommentierte Zeile. Aber ich denke, es macht den Code klarer, indem …

83 documentation  comments 

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 "Kommentare sollten Ihnen …

78 documentation  comments 

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 weiß …

72 project-management  documentation 

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 gehen. Ich habe das Gefühl, dass es schlecht für mein Gehirn …

66 career-development  documentation 

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 Funktionen in andere kleinere Funktionen aufteilen. Aber ich mache …

63 programming-practices  code-quality  documentation 

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 mehr verbosely erklären. Im besten Fall tut …

60 documentation  automation  automatic-programming 

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 bietet. Als Entwickler habe ich dieses Fenster als schnelle Statusanzeige …

59 documentation  component  jargon 

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> public Uri UpdateLocation …

54 programming-practices  documentation  language-agnostic 

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 werden?

49 git  documentation