Probleme bei Informationen mit kunden

  • Allgemein

Es gibt 19 Antworten in diesem Thema. Der letzte Beitrag () ist von Link.

    Probleme bei Informationen mit kunden

    Hallo Liebe Gemeinde,

    ich brauche mal eure Meinung.

    Ich bin bei einem Kunden gewesen, der sich bei mir beschwert hat, das ich zu wenig Informationen in die Codes geschrieben habe.
    Ich bin der Meinung, du musst den Code lesen und verstehen auch ohne Zusatz Infos.

    jetzt habe ich Ihm gesagt, es ist sinnvoll bei jeder Funktion bzw. Sub summary Infos zu schreiben.
    Jedoch reicht ihm das nicht, er möchte gerne das ich fast in jeder zeile schreibe was das tool bzw. Programm macht.

    Mich nervt es irgendwie.

    Ist das bei euch auch so?

    Gruß

    *Topic verschoben*

    Dieser Beitrag wurde bereits 1 mal editiert, zuletzt von „Marcus Gräfe“ ()

    Ich kommentiere meine Programme immer in fast jeder Zeile. Denn Jahre später braucht man sonst ewig, um alles zu verstehen. Im Privatbereich hat man vielleicht die Zeit, sich immer und immer wieder einzuarbeiten, aber im Berufsleben ist Zeit Geld. Also ich stimme deinem Kunden zu.
    Besucht auch mein anderes Forum:
    Das Amateurfilm-Forum
    Es stellt sich die Frage, wofür der Kunde bezahlt. Für ein fertiges Programm, für funktionierenden Code oder für für ihn verstehbaren Code. Das entscheidet m.E., worauf er Anspruch hat. Wenn er Dich für funktionierenden Code beauftragt hat und für ihn verstehbaren Code haben will, ist das m.E. eine Zusatzleistung, die auf seine Rechnung geht, da Deine zusätzliche Arbeitszeit, die für das Erreichen des vereinbarten/beauftragten Ziels für Dich nicht zeiteffektiv ist.

    Rattenfänger schrieb:

    Ist das bei euch auch so?
    Nee, meine Haupt-Kunden haben ganz andere Probleme, die nix mit Software zu tun haben (da ich hauptberuflich kein Software-Erzeuger bin).
    Dieser Beitrag wurde bereits 5 mal editiert, zuletzt von „VaporiZed“, mal wieder aus Grammatikgründen.

    Aufgrund spontaner Selbsteintrübung sind all meine Glaskugeln beim Hersteller. Lasst mich daher bitte nicht den Spekulatiusbackmodus wechseln.
    Wie @VaporiZed schon schrieb.
    Es kommt darauf an, was der Kunde bestellt hat.

    Wenn der Code verständlich geschrieben ist, erachte ich es eher als kontraproduktiv, hinter jeder Zeile nochmals die Übersetzung zu schreiben.
    Speziell VB.Net ist auch unkommentiert fast schon englische Prosa.
    Es gibt schon auch Zeilen, die eines erweiterten Kommentars bedürfen.
    Die sollten dann auch kommentiert werden.

    In meinen Augen viel wichtiger ist eine Dokumentation des Objektmodells, um die grundlegende Funktionsweise und den Workflow zu verstehen.

    Inline-Kommentare sind eine Gratwanderung zwischen zusätzlicher Erklärung und unnötiger Verwirrung.
    Die richtige Mischung zu treffen erfordert Erfahrung.
    Solche Zeilenkommentare sind aber generell nur dazu da, zukünftigen Programmierern, die den Code verändern oder erweitern sollen, als Hilfestellung zu dienen.
    Schau dir ein Programm an, das du letztes Jahr geschrieben hast und du merkst, wo Kommentare zu wenig oder zu viel sind.

    Inline-Kommentare sind nicht dazu da, Projektleitern oder Anwendern das Programmieren beizubringen.

    Wenn du von deinem Kunden aufgefordert wirst, jede Zeile zu kommentieren, kann das verschiedene Ursachen haben:
    - Dein Code an sich ist nicht sprechend (z.B. du verwendest kryptische Namen)
    -> verbessere deinen Programmierstil
    - Der Kunde ist kein Programmierer und versteht das Programm deswegen nicht
    -> Inline-Kommentare sind kein Ersatz für Schulungen
    - Du programmierst zu tricky
    -> Überlege, ob es nicht auch einfacher geht, wenn nein, dann schreibe die erklärenden Kommentare
    - Es gibt firmeninterne Richtlinien
    -> du musst dich daran halten oder von dem Projekt die Finger lassen
    - Er will dich schikanieren
    -> wehre dich oder lass es dir gefallen; abhängig von deiner Position. Manchmal kann man über unsinnige Anweisungen auch diskutieren.

    Generell gilt in unserem Wirtschaftssystem:
    Der Kunde ist König. Wer bezahlt, definiert die Spielregeln.
    Kläre beim nächsten Auftrag vorher, ob du mit den Spielregeln einverstanden bist.
    --
    If Not Program.isWorking Then Code.Debug Else Code.DoNotTouch
    --
    @Rattenfänger Stell Dir vor, Du machst ein Jahr lang Pause bei einem Projekt und schaust Dir Deinen eigenen Code nach diesem Jahr wieder an.
    Zwei Dinge werden Dir mindestens auffallen:
    1. Dein Programmierstil hat sich verfeinert (vorausgesetzt, Du hast zwischendurch weiter programmiert)
    2. Dein Code ist nicht ausreichend unf ggf. falsch kommentiert.
    Wenn ein Kunde Deinen Code lesen können soll, heißt das nicht, dass er einen Entwickler ein halbes Jahr abstellen muss, um ihn zu verstehen oder weiter zu entwickeln.
    Die Frage ist auch, was in dem Code passiert.
    Bei mathematischen Prozeduren sollte stehen, was sie tun und ggf. ein Link zu einer Web-Seite (FFT, Gauss-Jordan, ...) das genügt.
    Wenn Du aber programm-interne organisatorische Sachen schreibst, sollte da schon etwas mehr stehen.
    Insbesondere sind bei mir alle Prozeduren, die nicht EventHandler sind sowie alle EventHandler eigener Events mit /// bzw. '''-Kommentaren versehen.
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!
    Vielen Dank für eure zahlreichen Antworten,

    ja es klingt jetzt etwas einleuchtend die Codes mit ein paar mehr Kommentaren zu versehen.
    Da die Codes doch etwas komplexer sind. Nur muss ich dazu sagen wird es dem Kollegen nicht viel weiter helfen,
    da ihm schon viele Grundlagen in VB.Net fehlen(ist ja schon mächtig).

    Also noch mal herzlichen @Marcus Gräfe , @VaporiZed, @petaod, @RodFromGermany

    Gruß

    Rattenfänger schrieb:

    da ihm schon viele Grundlagen in VB.Net fehlen
    Die kannst Du selbstverständlich voraussetzen.
    Aber
    Du / Ihr könnt ja dem Kunden eine (ggf. kostenpflichtige) Einweisung in den Code anbieten.
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!
    Wichtig ist es den Funktionskopf mit allen Angaben zu versehen die wichtig für die Funktion sind.

    Innerhalb der Funktion setze ich gerne Kommentare, zum Teil auch vielzeilig, um mir später ins Gedächtnis zu rufen warum genau das so programmiert wurde.

    Aber das nur wenn es mir Erklärungsbedürftig erscheint.

    Ein Kunde der deinen Quellcode bekommt, sollte damit zufrieden sein.
    Jeder Entwickler der fremden Code weiterführt wird sich damit zurechtfinden.

    Ich programmiere nur noch beruflich und im Team, und habe immer wieder mit mir unbekanntem Code zu tun. Auch meine Kollegen kommen mit meinem Stil Kommentare zu setzen zurecht.

    Gruss

    mikeb69

    mikeb69 schrieb:

    und habe immer wieder mit mir unbekanntem Code zu tun.
    Fein, dass Du wieder mal online bist.
    Ja, das kommt mir sehr bekannt vor.
    Mein Chef kam schon mehrfach mit: Auf dem Server liegt eine Version von dem Projekt.
    Und die Kommenrtare waren praktisch nicht vorhanden.
    Da nehme ich mit einen Monat Zeit, fräse das Projekt durch und kommentrieren, was zu kommentieren ist.
    Manchmal ist nicht zu erkennen, was da gemeint ist, dan schreibe ich, was ich sehe, mit "???".
    Wenn ich dann in den nächsten Runden wieder da vorbei komme und besser Bescheid weiß, wird der Kommentar präzisiert.
    Also:
    @Rattenfänger Es ist besser, einen unrichtigen Kommentar mit einem entsprechenden Vermerk zu schreiben als gar keinen.
    Wichtig sind auch die // TODO | ' TODO-Kommentare, die werden dann im Projekt unter Ansicht => Aufgabenliste => Kommentare angezeigt.
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!

    Dieser Beitrag wurde bereits 1 mal editiert, zuletzt von „RodFromGermany“ ()

    @RodFromGermany Cool danke für den Hinweis mit TODO habe mich schon gefragt wie ich die Aufgabenliste füllen kann. Das könnte man natürlich als kleinen marker nutzen um schneller an bestimmte stellen zu springen. Cool Danke

    @mikeb69 ich schreibe zu 90% bei jeder sub bzw. Funktion die <summary> hier versuche ich zu erklären was die Funktion / Sub macht. Beim Rest muss man sich reinarbeiten und versuchen zu verstehen. Hier versuche ich auch den Variablen eindeutige/sprechende Namen zu geben.
    Da stellt sich mir gleich aber gleich mal die Frage: Wie groß sind Deine Subs/Functions? Ist das vielleicht auch ein Grund für die Forderung nach mehr Kommentierung? Meine Programme sind nicht sonderlich komplex. Aber selbst bei denen finde ich immer wieder Kandidaten, die ich in kleinere (sinnvolle!) Häppchen aufteilen kann. Und aus diesen Häppchen werden dann wieder Subs/Functions. "Moment. Aber geht es bei Prozedurerstellung nicht darum, diese an mehreren Stellen wiederzuverwenden?" Kann man so sehen, muss man aber nicht. Die meisten Prozeduren verwende ich nur an einer Stelle und erstelle sie nur deshalb, damit mir klar wird, was da in diesem Schritt inhaltlich* geschieht. Und das lasse ich den Codeleser (also mich) über den Prozedurnamen wissen. Daher sind meine aktuellen ( ;) ) Prozedurgrößen inzwischen bei ca. 5-10 Zeilen (zzgl. Rumpf). Manchmal hab ich sogar nur eine einzelne (komplexe) Zeile in einer Prozedur, aber die verpasst dem Code einen verständlichen Namen, sodass ich mir nicht beim Lesen immer** Gedanken machen muss, was codetechnisch, sondern nur inhaltlich passiert.

    *Nicht jede Kleinigkeit muss in ne eigene Prozedur. Aber Sachen, die zusammengehören. Das ist ein schleichender Prozess. In früheren Zeiten hatte ich gern mal >> 100-Zeilen-Monster. Dann habe ich angefangen, sie in einzelne (vielleicht 2-3) Teile zu hacken. Beim Lesen (einige Minuten bis einige Monate später) habe ich diese Einzelteile wieder zerhackt, weil ich sah, dass da immer noch zu viele Schritte zusammengefasst sind. Und inzwischen bin ich bei eben < 10 Zeilen (im Durchschnitt!)

    ** wenn ich natürlich den Inhalt der Prozedur anschaue, muss ich mich natürlich reinfitzeln, um ihn ggf. zu verbessern/vereinfachen/testen. Aber das geht besser, wenn ich dank des Prozedurnamens weiß, worauf ich mich inhaltlich einstellen muss. Und ggf. wird der Prozedurname angepasst, wenn er nicht ausreichend ausdrückt, was der Code an der Stelle in seiner Gesamtheit macht.
    Dieser Beitrag wurde bereits 5 mal editiert, zuletzt von „VaporiZed“, mal wieder aus Grammatikgründen.

    Aufgrund spontaner Selbsteintrübung sind all meine Glaskugeln beim Hersteller. Lasst mich daher bitte nicht den Spekulatiusbackmodus wechseln.
    @VaporiZed Na ja die haben verschiedene größen. Von klein(5-10) bis lang(ca 200 zeilen), je nach Anforderung. Es muss halt zur Sub/Funktion passen.
    Es ist halt auch so der Kunde kann zwar kleine vbscripte schreiben 5-30 zeilen. sobald jedoch komplexer funktion gebraucht werden also mit arrays oder api funktionen gearbeitet wird,
    wird es doch etwas zu komplex für ihn. Und bei der API möchte er halt wissen was die funktion macht. Ich selbst weiß es bzw. kann es anhand der funktion schon erkennen was die api funktion bedeutet.

    Nun sind die api Funktion von Microsoft bzw anderen anbietern sehr gut dokumentiert und man kann sich die Information aus den dokumenten holen. Das ist meine Meinung.

    so würde er es gerne habe

    VB.NET-Quellcode

    1. public sub SearchFeatures
    2. dim Swapp as sldworks.sldworks
    3. dim swmodeldoc as sldworks.Modeldoc2
    4. swapp = getobject(********) 'hole solidworks object
    5. swmodeldoc = swapp.getactivemodedov 'greife auf geöffnetes model zu
    6. if swmodeldoc.gettype = swDocumentTypes_e.swDocPART then
    7. 'durchsuche features
    8. for each swfeature as sldworks.feature in swmodeldoc.features
    9. next
    10. end if
    11. end sub


    ich schreibe die codes so

    VB.NET-Quellcode

    1. '''<summary>
    2. ''Durchsucht ein SolidWorks Teil nach Features
    3. '''</summary>
    4. public sub SearchFeatures
    5. dim Swapp as sldworks.sldworks
    6. dim swmodeldoc as sldworks.Modeldoc2
    7. swapp = getobject(********)
    8. swmodeldoc = swapp.getactivemodedov
    9. if swmodeldoc.gettype = swDocumentTypes_e.swDocPART then
    10. for each swfeature as sldworks.feature in swmodeldoc.features
    11. next
    12. end if
    13. end sub
    Du hast mein Mitleid - bei den Wünschen solchen Code noch dokumentiert haben zu wollen geht mir der Hut hoch...

    Was soll man denn da noch dokumentieren - das ist doch ganz einfach menschenlesbare Prosa (allerdings in Englisch), keine mathematischen Formeln, vererbten Objektmodelle, Klassen, Differentiale, Integrale oder was weiß ich was!

    Meine Meinung: Wenn er sich da nicht reinlesen kann dann soll er's sein lassen mit programmieren oder eben die Grundlagen lernen! Allerdings bist du hier in dem Dilemma dass der Kunde schon irgendwie König ist... Nur - wenn das dann so gut dokumentiert ist wie's der Kunde möchte und der dann (erfolglos...???) dran herumpgrogrammiert hör ich schon die Nachtigall trapsen dass du dann auch noch Schuld bist wenn's nicht funktioniert...
    Hmm - ich finde den Code durchaus noch verbesserungfähig.
    Vor allem ist da Strict Off geproggt - solch ist immer wieder für fies zu debuggende Laufzeitfehler und v.a. Fehlverhalten (ohne Exception) gut.

    Zb dies hier:

    VB.NET-Quellcode

    1. If swmodeldoc.gettype = swDocumentTypes_e.swDocPART Then
    Da bin ich etwas skeptisch, ob das das macht, was Rattenfänger denkt, was es macht.
    Aber ich kenne das SolidWorks-Framework nicht - vielleicht bedeutet dort .GetType() was anneres als im .Net-Framework.
    Bzw swDocumentTypes_e.swDocPART ist tatsächlich ein System.Type (was sehr unkonventionell wäre).

    Weiters beschreibt die Summary eiglich garnix - die Methode heisst ja schon so.
    Für mich als Leser offen bleibt die Frage, was die Methode denn nun mit den gefundenen Features anstellt.
    Einen Rückgabewert gibts ja nicht - also was tut die Methode damit?
    Das wäre in meinen Augen zu dokumentieren.
    (Oder statt dieses zu dokumentieren die Architektur ändern, und der Methode eben doch einen Rückgabewert verpassen, der verarbeitet wird)



    Ups - sorry, darum gings ja eiglich garnet.
    Jo, zur Kommentation bin ich auf Rattenfängers Seite: Was der Kunde sich da wünscht ist Unfug, und lenkt nur von wesentlichen Fragen (wie ich sie imo etwa oben gestellt habe) ab.

    Damit hätte ich auch meine emotionalen Probleme.
    ist eigentümlich, wie sehr es einem (mir zumindest) an die Nerven geht, wenn man gezwungen wird, eindeutig schlechteren Code zu schreiben, als man könnte und wollte.
    Eiglich sollte man sich doch als Dienstleister begreifen: "Du zahle, ich mach".

    Dieser Beitrag wurde bereits 1 mal editiert, zuletzt von „ErfinderDesRades“ ()

    Ja, das Solidworks-Framework ist ein wenig "speziell". Das ist wohl auch der Grund dafür dass "StrictOff" programmiert ist, wobei mittlerweile kann man's schon in "StrictOn" zwingen - das setzt aber eine halbwegs aktuelle Solidworks-Version (glaube ab 2017) voraus...

    Dass jetzt hier nicht gepostet wurde was die Funktion tut - naja is ja irgendwie nachvollziehbar, als Beispiel reicht das doch so..
    Ich bleibe trotzdem bei meiner Meinung - Kommentare sind nicht dazu da einem unbedarften Leser die Grundlagen der Programmierung beizubringen! Und falls es hier um die spezielle Solidworks-API geht - die ist recht gut und umfangreich dokumentiert!
    @ErfinderDesRades option strict on habe ich mir angewöhnt einzustellen.
    Den Code habe ich auf die schnelle hier auf der website erstellt. Im richtigen code sieht das anders.

    Ja .gettype zeigt den Dokumenttypen an(also Teil, Baugruppe, Zeichnung) Das sollte er aber wissen, wenn er codes ändern will. Grundlage!!!
    swDocumentTypes_e.swDocPART ist eine solidworks API constante, die natürlich in vb.net impotiert ist, da werden dann die Integer Werte aufgeschlüsselt.

    als bsp.

    1 = swDocumentTypes_e.swDocPART
    2 = swDocumentTypes_e.swAssembly
    3 = swDocumentTypes_e.Drawing

    und so weiter.

    ja klar, wenn diese Methode es verarbeiten würde, würde ich es in die summary schreiben. ansonsten wenn es ein verweis auf eine andere Function ist, dann schreibe ich was die Function macht(also in der summary).
    In VB.net ist es ja schön wenn ich mit der maus auf einen Verweis gehe sehe ich ja die summary.

    Und der Code selbst macht ja auch nichts, als die Features zu durchlaufen :-). so wie es in dem Methoden Namen steht bzw. Summary.

    Edit:

    @Thisoft es funktioniert mit strict on. mann muss halt alle objecte ctypen(umwandeln), wobei sie ja jetzt extra für vb.net die isldworks haben, hier sind die objekte schon richtig gewandelt.also feature = feature und nicht object = feature.
    Meine Kunden wollten auch immer das alles genaustens dokumentiert war. War für mich selbstverständlich für spätere Abnehmer der Software die das dann weiterführen wollten. Ein Kunde wollte sogar das ich ers in einem Word Dokument dokumentiere, das ging mir dann zu weit.
    Metal-Schweiz wurde nun offiziell veröffentlich nach all den Jahren :)

    @Orion Das kannst Du doch dem kunden als bezahlungspflichtigen Service anbieten.
    Mach den Preis entsprechend hoch, da kommt wenigstens was rein, wenn er es immer noch haben will. :D
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!
    @RodFromGermany Das Problem war, ich war damals noch als Azubi angestellt, daher hatte ich gar nichts zu melden.
    Metal-Schweiz wurde nun offiziell veröffentlich nach all den Jahren :)

    Hi,

    pauschal kann man da, wie andere schon gesagt haben, eigentlich keine Aussage treffen. Was hat der Kunde bestellt? Nur das is wichtig.
    Methodenkommentare sind normalerweise sowieso immer dabei, zu jeder Methode oder Eigenschaft also zumindest eine kurze Erklärung wofür es ist und pro Klasse womöglich noch eine Zusammenfassung, letzteres kann aber auch extern in eine Dev-Doku mit rein. Jede Zeile zu kommentieren ist selten hilfreich. Man sollte versuchen, so zu programmieren dass der Code für das geübte Auge schon beim Überfliegen selbsterklärend ist. Klar, komplexe Stellen können nochmal extra exklärt werden, aber wenn Variablen, Eigenschaften und Methoden bereits einigermaßen ordentlich benannt sind, hilft das schon viel. Wenn man mit Codeconventions arbeitet dann sind die Methoden bestenfalls schon kurz gehalten und logisch verteilt, sodass man sich durch kein langes Codegewurschtel scrollen muss, was super-ätzend ist. Wenn alles angemessen abstrahiert und clean ist, hilft es schon von ganz allein, den Code beim Lesen besser und schneller zu erfassen und zu verstehen. Grundsätzlich sollte Code immer in Englisch geschrieben werden, gilt für Klassen, Variablen, Methoden und Kommentare. In der Regel kann jeder Programmierer recht gut Englisch (oder andersrum kenne zumindest ich niemanden auf den das nicht so zutreffen würde).

    Je nach Projekt und Anforderung kann noch eine Enduser-Doku geschrieben werden (für Nicht-Devs) sowie eine Dev-Doku für Entwickler die später mal an dem Projekt weiterarbeiten. Wenn dein Code modular ist, kannst du auch überlegen, in die jeweiligen Verzeichnisse eine Markdown-Readme reinzupacken und dort grob die gesamtheitliche Logik darzulegen.

    Überleg auch wie wortreich du bei den jeweiligen zu kommentieren Stellen sein willst. Du kannst zeilenweise kommentieren, pro Methode, pro Datei oder Klasse, du kannst separate readme.md Dateien in Verzeichnissen ablegen, vielleicht gibt's eine Enduser- oder Dev-Doku und wenn du ein VCS benutzt schreibst du ja auch noch commit-messages, bei externen Tools (Jira, Trello, whatever) schreibst du zusätzlich pro Task auch noch was du gemacht hast. Das kann echt viel werden. Ist auf dauer ranzig wenn du feststellst dass du dich permanent wiederholst und die Kommentare redundant werden. Hier ist es reine Erfahrungssache, das sinnvoll auszuloten und die Verbosität adäquat zu verteilen.

    Jedoch reicht ihm das nicht, er möchte gerne das ich fast in jeder zeile schreibe was das tool bzw. Programm macht.

    Was er theoretisch möchte oder nicht ist irrelevant. Wenn er dich dafür extra bezahlt dass du diese Kommentaränderung vornimmst, ist das doch ok. Liegt ja dann nur noch an dir, du entscheidest dann ob du es machen möchtest oder nicht. Naja, wenn das nun von Anfang an eine Anforderung war die du dann einfach nicht umsetzen wolltest oder ignoriert hast, hast du aber jetzt eh ein Problem.


    Link :thumbup:
    Hello World