Εργασία ως προγραμματιστής υπό δύσκολες συνθήκες

[liakos356]

8 ώρες πριν, skiabox είπε

Φυσικά το να μην βάζεις σχόλια στον κώδικά σου είναι από τις χειρότερες προγραμματιστικές πρακτικές που μπορεί να υπάρξουν.

 

4 ώρες πριν, skiabox είπε

Για αυτό λέμε για το management της πληροφορικής.

Φαντάσου να είσαι στο ίδιο team με τον από πάνω και να μη σου βάζει σχόλια ποτέ!

Πιθανότατα υπέρ-ταλαντούχος αλλά δεν μπορεί να συνεργαστεί με κανέναν.

Και επίσης πιθανότατα εγωίσταρος.

 

Τα σχόλια θα μπουν στο task description. Το task θα έχει συγκεκριμένα specs, ώστε να ξέρει ο καθένας το πρέπει να παραδώσει. Είμαστε στο 2020 και υπάρχουν συγκεκριμένα process και εργαλεια για project management . Άντε να δικαιολογησω κάποιο //TODO στο develop branch , αλλά μέχρι εκεί. Για production δε το συζητάμε, ούτε κατα διάνοια. Είναι απλά θόρυβος για όσους εμπλέκονται στο project. 

Το γράψιμο και η συντήρηση σχολίων μέσα στο codebase επιβαρύνουν το devepoment process χωρίς ουσιαστική ανταποδοτική αξία. Αν πρέπει να εξηγείς περιφραστικα τι κάνει το function, τότε έχεις παραβει το single responsibility rule. 

Ο σωστός κώδικας είναι περιγραφικός από μόνος του. Δεν χρειάζεται σχόλια. Ένας έμπειρος προγραμματιστης ξέρει πως να δομησει και ονοματισει τα components του ώστε να βγαίνει νόημα. 

Κάπου είχα ακούσει μια συμβουλή και ήταν πραγματικά spot on. Ο κώδικας είναι σαν ένα ανέκδοτο. Αν χρειαστεί να το εξηγήσεις, τότε έχεις κάνει κάτι λάθος. Έτσι και με τον κώδικα σου. Πρέπει αυτός που τον διαβάζει, να τον καταλαβαίνει κατευθείαν. Αν αυτό δε συμβαίνει, δεν προσπαθείς να τον εξηγεις με comments. Πας πίσω στον editor και κάνεις refactoring. 

Το documentation είναι ξεχωριστό κεφάλαιο όπου πρέπει να το έχεις συγκεντρωμενο κάπου κεντρικά ώστε να γινεται reference και update όσο πιο εύκολα γίνεται. 

Όσο για το θέμα του εγωισμού και κατά πόσο μπορεί  να συνεργαστεί, ας κοιτάξει πρώτα να γράψει τα unit test του, να περάσει τον linter, να περάσει το e2e test, να περάσει το code review που θα του κάνει η ομάδα , να ακολουθεί το git-flow της ομάδας , να περασει το regression test, να ενημερώσει το task στο board και χάρισμα του τα comments. Μια χαρά βγάζεις άκρη και χωρίς αυτά. 

Επεξ/σία 9 Δεκεμβρίου 2020 από liakos356

[Papakaliati]

5 ώρες πριν, liakos356 είπε

Τα σχόλια θα μπουν στο task description. Το task θα έχει συγκεκριμένα specs, ώστε να ξέρει ο καθένας το πρέπει να παραδώσει. Είμαστε στο 2020 και υπάρχουν συγκεκριμένα process και εργαλεια για project management . Άντε να δικαιολογησω κάποιο //TODO στο develop branch , αλλά μέχρι εκεί. Για production δε το συζητάμε, ούτε κατα διάνοια. Είναι απλά θόρυβος για όσους εμπλέκονται στο project. 

Το γράψιμο και η συντήρηση σχολίων μέσα στο codebase επιβαρύνουν το devepoment process χωρίς ουσιαστική ανταποδοτική αξία. Αν πρέπει να εξηγείς περιφραστικα τι κάνει το function, τότε έχεις παραβει το single responsibility rule. 

Ο σωστός κώδικας είναι περιγραφικός από μόνος του. Δεν χρειάζεται σχόλια. Ένας έμπειρος προγραμματιστης ξέρει πως να δομησει και ονοματισει τα components του ώστε να βγαίνει νόημα. 

Κάπου είχα ακούσει μια συμβουλή και ήταν πραγματικά spot on. Ο κώδικας είναι σαν ένα ανέκδοτο. Αν χρειαστεί να το εξηγήσεις, τότε έχεις κάνει κάτι λάθος. Έτσι και με τον κώδικα σου. Πρέπει αυτός που τον διαβάζει, να τον καταλαβαίνει κατευθείαν. Αν αυτό δε συμβαίνει, δεν προσπαθείς να τον εξηγεις με comments. Πας πίσω στον editor και κάνεις refactoring. 

Το documentation είναι ξεχωριστό κεφάλαιο όπου πρέπει να το έχεις συγκεντρωμενο κάπου κεντρικά ώστε να γινεται reference και update όσο πιο εύκολα γίνεται. 

Όσο για το θέμα του εγωισμού και κατά πόσο μπορεί  να συνεργαστεί, ας κοιτάξει πρώτα να γράψει τα unit test του, να περάσει τον linter, να περάσει το e2e test, να περάσει το code review που θα του κάνει η ομάδα , να ακολουθεί το git-flow της ομάδας , να περασει το regression test, να ενημερώσει το task στο board και χάρισμα του τα comments. Μια χαρά βγάζεις άκρη και χωρίς αυτά. 

Το ότι ο σωστός κώδικας είναι περιγραφικός από μόνος του και δεν χρειάζεται σχόλια, και ότι τα σχολια είναι code smell, ειναι απο τις μεγαλυτερες μπαρουφες ever, που καποιος εγραψε και απο τοτε εχει γινει ευαγγελιο, απο τους πιο αδυναμους κυριως μιας ομαδας. 

Και τι σχέση έχει ο κώδικας με ανέκδοτο; Η παρομοίωση θα είχε νόημα, άμα μιλούσαμε για 2 άντε 3 μεθόδους με 5 γραμμές η κάθε μια (κανένα python scriptaki), όχι για ένα ολόκληρο σύστημα 10.000 γραμμών και 100 αρχείων. Αυτο ειναι πες σε εναν ενα ανεκδοτο 5 ωρες, με το αστειο να συνδεετε με κατι που ειπες στα πρωτα 5 λεπτα.  Σοβαρευτείτε λίγο, και μην ακολουθείται τυφλά ότι διαβάζεσαι σε ένα πόστ. Όταν ολόκληρος Linus Torvalds η ολοκληρες γλωσσες και frameworks εχουνε comments στο source code: Typescript , K8s κτλ, τι σε κανει να πιστευεις οτι εσυ ξερεις καλυτερα; Επειδη το διαβασες μια φορα σε ενα μπλογκ; Ξεκαβαλιστε την μονοπλευρη λογικη σας, μπας και καταφερε να γινετε λιγο καλυτεροι στην δουλεια σας.

Η νομεκλατουρα, που τόσο επιμένετε ότι είναι self explanatory, μπορει σε καποιον αλλον να μην βγαζει κανενα νοημα, ενω σε εσενα να φαινεται οτι περιγραφει την ομορφια ολου του κοσμου. Επειδη εσεις εχετε ομως την σφαιρικη εικονα ενως συστηματος, ενω καποιος αλλος οχι. Δεν γραφουν καταρχην ολοι για κωδικα ενα πανευκολακι απι, διαβασε ενα request, παρε query τον πινακα και μετα και επεστρεψε το αντικειμενο. 

Σχόλια όταν λέμε να εξηγούν γιατί κανεις κάτι, όχι πως το κανείς. Δεν θα γράφεις ->

// Σε αυτό το for θα δούμε άμα υπάρχει το ID που ζηταμε σε αυτην την λιστα, χαιρω πολυ. 

Θα γράψεις όμως ->

// Στα στοιχεία της λίστας για να εφαρμόσουμε το φιλτράρισμα ακολουθώντας την εξής σειρά, όπως συμφωνήθηκε με το εξής jira task ΜΧΣ:xxxxx, ID -> ΚΕΥ, Τιτλε...   

Γιατί κάποιος που πρώτη φορά διαβάζει τον κώδικα, θα πει, τι φάση; Δεν είναι ότι δεν θα καταλάβει τον κώδικα, αλλά φυσικά δεν ξέρει το background ωστε να μπορει να κατανοησει της αποφασεις σας. Οποτε πραγματικά, καντε ολους μια χαρη και σταματηστε να πιστευεται οτι η ελλειψη σχολίων σας κάνει μαγικά καλύτερους γνωστές του αντικειμένου.  

Ξέρεις αλήθεια τι είναι καλύτερο από έναν τέλεια γραμμένα κώδικα που καταλαβαίνεις κατευθείαν τα πάντα; Ένας τέλεια γραμμένος κώδικας, έστω και με φαινομενικά περιττά comments. Θα σε κανουν τα κομμεντς ποτε να καταλαβεις λιγοτερα απο τον κωδικα; Ποτε δεν θα γινεται αυτο; Θα σε κανουν να καταλαβεις περισσοτερα; Πολυ πιθανο. 

Επεξ/σία 9 Δεκεμβρίου 2020 από Papakaliati

[Kercyn]

9 ώρες πριν, Papakaliati είπε

Καλά πως. Σχόλια δεν γράφεις (μόνο) για να εξηγείς πως κανεις κάτι, αλλά και γιατί. Πχ έχεις διαλέξει ένα magic number σε configuration: γράψε γιατί. Σε ένα απι για παράδειγμα μπορεί να παίρνεις σαν απάντηση όχι το αποτέλεσμα , αλλά επειδή είναι asynchronous, το αποτέλεσμα να είναι το operation ID. Ε θέλεις να το σημειώσεις στο κώδικα σου, αλλιώς μετά από 6 μήνες θα κοιτάς και απορείς γιατί το έκανες αυτό. 1002 παραδείγματα μπορείς να βρεις παρόμοια.

Τα δύο παραδείγματα αυτά λύνονται πολύ εύκολα αν ορίσεις το magic number σε ένα const με κατάλληλο όνομα και αν ονομάσεις τη συνάρτηση κατάλληλα έτσι ώστε αυτός που την καλεί να μην έχει ψευδαισθήσεις για το τι θα πάρει πίσω, αναφέροντας παράλληλα και στο documentation σου πώς λειτουργεί το API σου.

Ξαναλέω, δεν ισχυρίζομαι ότι όλα τα comments είναι κακά. Αυτό που λέω είναι ότι γίνεται μεγάλο misuse και στην τελική καταλήγεις να σπαταλάς χρόνο κάθε φορά που βλέπεις ένα σχόλιο για να καταλάβεις αν αυτά που γράφει το σχόλιο ανταποκρίνεται στον κώδικα και αν προσφέρει κάτι ουσιαστικό. Το νόημα ενός σχολίου είναι να σου γλυτώσει mental load, όχι να σου προσθέσει επιπλέον. Μην ξεχνάμε ότι για κάθε σύστημα θα πρέπει να υπάρχει documentation το οποίο θα εξηγεί πώς δουλεύει, δεν είναι δουλειά των σχολίων να σου εξηγήσουν την αρχιτεκτονική όλου του συστήματος.

[Επισκέπτης]

17 λεπτά πριν, Kercyn είπε

Ξαναλέω, δεν ισχυρίζομαι ότι όλα τα comments είναι κακά. Αυτό που λέω είναι ότι γίνεται μεγάλο misuse και στην τελική καταλήγεις να σπαταλάς χρόνο κάθε φορά που βλέπεις ένα σχόλιο για να καταλάβεις αν αυτά που γράφει το σχόλιο ανταποκρίνεται στον κώδικα και αν προσφέρει κάτι ουσιαστικό. Το νόημα ενός σχολίου είναι να σου γλυτώσει mental load, όχι να σου προσθέσει επιπλέον. Μην ξεχνάμε ότι για κάθε σύστημα θα πρέπει να υπάρχει documentation το οποίο θα εξηγεί πώς δουλεύει, δεν είναι δουλειά των σχολίων να σου εξηγήσουν την αρχιτεκτονική όλου του συστήματος.

Πως αντιμετωπίζεις την έλλειψη documentation αλλά και σχολίων;

[ghostaki]

2 ώρες πριν, Papakaliati είπε

Όταν ολόκληρος Linus Torvalds η ολοκληρες γλωσσες και frameworks εχουνε comments στο source code: Typescript , K8s κτλ,

Καλά, 15 γραμμές σχόλια σε ένα αρχείο 800 γραμμών δε τα λες και πολλά. Επίσης γιατί ο κώδικας της TS να είναι ευαγγέλιο / στο απυρόβλητο;

Είμαι κι εγώ στο στρατόπεδο του "τα σχόλια στην πυρά" 😄, εκτός κι αν υπάρχει κάποιος πολύ καλός λόγος για λίγα και στοχευμένα σχόλια. Συνήθως όταν νιώθω την ανάγκη να βάλω σχόλιο, σύντομα συνειδητοποιώ ότι η ανάγκη για refactoring ή απλά για καλύτερα ονόματα είναι ακόμη μεγαλύτερη. 

Επίσης, η εμπειρία (μου) έχει δέιξει ότι σχόλια συνήθως καταλήγουμε να βάζουμε σε σημεία που εκτελούν κάποιο πολύ περίεργο/πολύπλοκο business logic. Και το σχόλιο τότε δεν έχει σκοπό να εξηγήσει τον κώδικα, αλλά το business rule που εκτελεί ο κώδικας. Και σε αυτές τις περιπτώσεις το πρόβλημα πρέπει να το λύσει ο/η ΒΑ και όχι ο developer. Γιατί το software δεν υπάρχει σε ένα κενό αέρος, αλλά εξυπηρετεί κάποιες ανάγκες. Κι όταν αυτές είναι μπερδεμένες ή αλλάζουν συνέχεια, τότε υποφέρει και ο κώδικας.

Καταλαβαίνω επίσης ότι όλοι μας γράφουμε κώδικας ο καθένας στο δικό του κομμάτι/domain/κλπ και αυτό μπορεί να σημαίνει ότι κάτι που δουλεύει για κάποιον δε δουλεύει για κάποιον άλλον.

Τέλος, ας μην αναλωνόμαστε σε λογικές ο κώδικάς μου είναι καλύτερος γιατί είναι 10kloc και 100 αρχεία, ο δικός σου είναι σκριπτάκι μπροστά του, δεν οδηγούν πουθενά 🙂

1 ώρα πριν, asxs είπε

Πως αντιμετωπίζεις την έλλειψη documentation αλλά και σχολίων;

Μια αφελής ερώτηση από μένα: όταν λέμε documentation, τι ακριβώς εννοούμε; Ρωτάω γιατί σε όσα προτζεκτ  έχω δουλέψει ποτέ δεν έχω δει documentation για κώδικα. Παρά μόνο για library components που έχουν ενα readme για το πως να τα χρησιμοποιήσεις.

Επίσης documentation υπάρχει πάντα για το όλο σύστημα (architecture), αλλά αυτό δεν έχει να κάνει με τον κώδικα. Ο κώδικας είναι self-documented, στην ιδανική περίπτωση τουλάχιστον.

[Papakaliati]

35 λεπτά πριν, ghostaki είπε

Καλά, 15 γραμμές σχόλια σε ένα αρχείο 800 γραμμών δε τα λες και πολλά. Επίσης γιατί ο κώδικας της TS να είναι ευαγγέλιο / στο απυρόβλητο;

Είμαι κι εγώ στο στρατόπεδο του "τα σχόλια στην πυρά" 😄, εκτός κι αν υπάρχει κάποιος πολύ καλός λόγος για λίγα και στοχευμένα σχόλια. Συνήθως όταν νιώθω την ανάγκη να βάλω σχόλιο, σύντομα συνειδητοποιώ ότι η ανάγκη για refactoring ή απλά για καλύτερα ονόματα είναι ακόμη μεγαλύτερη. 

Επίσης, η εμπειρία (μου) έχει δέιξει ότι σχόλια συνήθως καταλήγουμε να βάζουμε σε σημεία που εκτελούν κάποιο πολύ περίεργο/πολύπλοκο business logic. Και το σχόλιο τότε δεν έχει σκοπό να εξηγήσει τον κώδικα, αλλά το business rule που εκτελεί ο κώδικας. Και σε αυτές τις περιπτώσεις το πρόβλημα πρέπει να το λύσει ο/η ΒΑ και όχι ο developer. Γιατί το software δεν υπάρχει σε ένα κενό αέρος, αλλά εξυπηρετεί κάποιες ανάγκες. Κι όταν αυτές είναι μπερδεμένες ή αλλάζουν συνέχεια, τότε υποφέρει και ο κώδικας.

Καταλαβαίνω επίσης ότι όλοι μας γράφουμε κώδικας ο καθένας στο δικό του κομμάτι/domain/κλπ και αυτό μπορεί να σημαίνει ότι κάτι που δουλεύει για κάποιον δε δουλεύει για κάποιον άλλον.

Τέλος, ας μην αναλωνόμαστε σε λογικές ο κώδικάς μου είναι καλύτερος γιατί είναι 10kloc και 100 αρχεία, ο δικός σου είναι σκριπτάκι μπροστά του, δεν οδηγούν πουθενά 🙂

Μια αφελής ερώτηση από μένα: όταν λέμε documentation, τι ακριβώς εννοούμε; Ρωτάω γιατί σε όσα προτζεκτ  έχω δουλέψει ποτέ δεν έχω δει documentation για κώδικα. Παρά μόνο για library components που έχουν ενα readme για το πως να τα χρησιμοποιήσεις.

Επίσης documentation υπάρχει πάντα για το όλο σύστημα (architecture), αλλά αυτό δεν έχει να κάνει με τον κώδικα. Ο κώδικας είναι self-documented, στην ιδανική περίπτωση τουλάχιστον.

Παίδες, πρέπει να καταλάβετε ένα απλό πράγμα. Δεν ενδιαφέρει κανέναν το πως βλέπετε εσείς τα σχόλια. Το κάνετε για άλλους (η για το εαυτό σας που θα κοιτάξει τον κώδικα σε έναν χρόνο από τώρα). Όταν έχετε κάτσει να γράψετε τον κώδικα, ξέρετε ακριβώς τι κάνει και έχετε μια σφαιρική ματιά. Αυτό που θεωρείται εσείς καλογραμμένο και φως φανάρι, ε για τον άλλο που θα το διαβάσει δεν θα του φαίνεται καθόλου έτσι, και θα τραβάει τα βυζια του προσπαθώντας να καταλάβει τι προσπαθούσατε να κάνετε. Κάντε σε όλους μια χάρη, και ξεκολλιέστε από την νοοτροπία ¨τα σχόλια στην πυρά¨. 

2 ώρες πριν, Kercyn είπε

Τα δύο παραδείγματα αυτά λύνονται πολύ εύκολα αν ορίσεις το magic number σε ένα const με κατάλληλο όνομα και αν ονομάσεις τη συνάρτηση κατάλληλα έτσι ώστε αυτός που την καλεί να μην έχει ψευδαισθήσεις για το τι θα πάρει πίσω, αναφέροντας παράλληλα και στο documentation σου πώς λειτουργεί το API σου.

Ξαναλέω, δεν ισχυρίζομαι ότι όλα τα comments είναι κακά. Αυτό που λέω είναι ότι γίνεται μεγάλο misuse και στην τελική καταλήγεις να σπαταλάς χρόνο κάθε φορά που βλέπεις ένα σχόλιο για να καταλάβεις αν αυτά που γράφει το σχόλιο ανταποκρίνεται στον κώδικα και αν προσφέρει κάτι ουσιαστικό. Το νόημα ενός σχολίου είναι να σου γλυτώσει mental load, όχι να σου προσθέσει επιπλέον. Μην ξεχνάμε ότι για κάθε σύστημα θα πρέπει να υπάρχει documentation το οποίο θα εξηγεί πώς δουλεύει, δεν είναι δουλειά των σχολίων να σου εξηγήσουν την αρχιτεκτονική όλου του συστήματος.

Φυσική και δεν είναι έτσι. Πως θα ονομάσεις δηλαδή την μεταβλητή σου MagicNumberOfPerfectExecutionsThatPaper$12332AndDiscussionWithJimAndJohnSeemedToProvideTheBestResultsAndAfterThisBenefitsDecreesDramatically ?

To Magic Number δεν εχει δουλεια στο API documentation, δεν ειναι κατι που ενδιαφερει τον API user, ειναι κατι που ενδιαφερει αυτον που θα πρεπει να συντηρησει, επεκτυνει, debuggarei των κωδικα σου στο μελλον.  

Επεξ/σία 9 Δεκεμβρίου 2020 από Papakaliati

[ghostaki]

4 λεπτά πριν, Papakaliati είπε

Παίδες, πρέπει να καταλάβετε ένα απλό πράγμα. Δεν ενδιαφέρει κανέναν το πως βλέπετε εσείς τα σχόλια. Το κάνετε για άλλους (η για το εαυτό σας που θα κοιτάξει τον κώδικα σε έναν χρόνο από τώρα). Όταν έχετε κάτσει να γράψετε τον κώδικα, ξέρετε ακριβώς τι κάνει και έχετε μια σφαιρική ματιά. Αυτό που θεωρείται εσείς καλογραμμένο και φως φανάρι, ε για τον άλλο που θα το διαβάσει δεν θα του φαίνεται καθόλου έτσι, και θα τραβάει τα βυζια του προσπαθώντας να καταλάβει τι προσπαθούσατε να κάνετε. Κάντε σε όλους μια χάρη, και ξεκολλιέστε από την νοοτροπία ¨τα σχόλια στην πυρά¨. 

Βασικά τίποτα δε πρέπει να καταλάβουμε, κουβέντα για ανταλλαγή απόψεων κάνουμε. Ας ακολουθεί ο καθένας την πορεία με την οποία είναι χαρούμενος και δεδομένου ότι οι πιθανότητες να συνυπάρξουμε εργασιακά είναι εξαιρετικά μικρές το ίδιο μικρές είναι και οι πιθανότητες να χρειαστεί να δουλέψει ο ένας με τον κώδικά του άλλου 🙂 

4 λεπτά πριν, Papakaliati είπε

Φυσική και δεν είναι έτσι. Πως θα ονομάσεις δηλαδή την μεταβλητή σου MagicNumberOfPerfectExecutionsThatPaper$12332AndDiscussionWithJimAndJohnSeemedToProvideTheBestResultsAndAfterThisBenefitsDecreesDramatically ?

Αν το όνομα αυτό πραγματικά αντικατοπτρίζει το τι αντιπροσωπεύει αυτή η μεταβλητή, τότε το όνομα θα μπορούσε απλά να είναι "numberOfPerfectExecutions" και ένα απλό σχόλιο που να δίνει link για το που έγινε η συζήτηση με τον John και τον Jim. Και στη συζήτηση θα υπάρχει και το link για το paper και ό,τι άλλο χρειάζεται. Tώρα, αν δεν υπάρχει link για τη συζήτηση αυτή, τότε το πρόβλημα βρίσκεται αλλού και όχι στον κώδικα.

[Kercyn]

1 ώρα πριν, asxs είπε

Πως αντιμετωπίζεις την έλλειψη documentation αλλά και σχολίων;

Με πολλά ξεφυσήματα κυρίως. Δεν καταλαβαίνω τι ακριβώς ρωτάς.

 

15 λεπτά πριν, Papakaliati είπε

Φυσική και δεν είναι έτσι. Πως θα ονομάσεις δηλαδή την μεταβλητή σου MagicNumberOfPerfectExecutionsThatPaper$12332AndDiscussionWithJimAndJohnSeemedToProvideTheBestResultsAndAfterThisBenefitsDecreesDramatically ?

To Magic Number δεν εχει δουλεια στο API documentation, δεν ειναι κατι που ενδιαφερει τον API user, ειναι κατι που ενδιαφερει αυτον που θα πρεπει να συντηρησει, επεκτυνει, debuggarei των κωδικα σου στο μελλον.  

Δεν είπα ότι το magic number εχει δουλειά στα docs. Αυτό που λέω είναι ότι αν βρεις την ανάγκη να χρησιμοποιήσεις ένα magic number στο οποίο, για τους λόγους της συζήτησης, δε μπορείς να δώσεις ένα περιγραφικό όνομα για το τι είναι, τότε ίσως θα πρέπει να κάνεις ένα βήμα πίσω και να δείς το γιατί χρειάζεσαι αυτό το magic number. Μήπως θα μπορούσες να δομήσεις καλύτερα τον κώδικα για να εξαλειφθεί η ανάγκη του magic number; Αν πια φτάσεις στο σημείο που δεις ότι για τον έναν ή τον άλλο λόγο πρέπει να υπάρχει αυτό το magic number, γράφεις ένα σχόλιο που εξηγείς ακριβώς τι είναι αυτό και γιατί υπάρχει.

Ξαναλέω ότι το πρόβλημά μου είναι ότι πολλές φορές τα σχόλια αποτελούν έναν εύκολο, τεμπέλικο και error-prone τρόπο να γλυτώσει ο developer από μαγικές αποφάσεις και τεχνικές που υλοποιεί στον κώδικα.

[tsofras]

19 λεπτά πριν, Papakaliati είπε

Παίδες, πρέπει να καταλάβετε ένα απλό πράγμα. Δεν ενδιαφέρει κανέναν το πως βλέπετε εσείς τα σχόλια. Το κάνετε για άλλους (η για το εαυτό σας που θα κοιτάξει τον κώδικα σε έναν χρόνο από τώρα). Όταν έχετε κάτσει να γράψετε τον κώδικα, ξέρετε ακριβώς τι κάνει και έχετε μια σφαιρική ματιά. Αυτό που θεωρείται εσείς καλογραμμένο και φως φανάρι, ε για τον άλλο που θα το διαβάσει δεν θα του φαίνεται καθόλου έτσι, και θα τραβάει τα βυζια του προσπαθώντας να καταλάβει τι προσπαθούσατε να κάνετε. Κάντε σε όλους μια χάρη, και ξεκολλιέστε από την νοοτροπία ¨τα σχόλια στην πυρά¨. 

Φυσική και δεν είναι έτσι. Πως θα ονομάσεις δηλαδή την μεταβλητή σου MagicNumberOfPerfectExecutionsThatPaper$12332AndDiscussionWithJimAndJohnSeemedToProvideTheBestResultsAndAfterThisBenefitsDecreesDramatically ?

To Magic Number δεν εχει δουλεια στο API documentation, δεν ειναι κατι που ενδιαφερει τον API user, ειναι κατι που ενδιαφερει αυτον που θα πρεπει να συντηρησει, επεκτυνει, debuggarei των κωδικα σου στο μελλον.  

Όλα σχετικά είναι ρε μαν και εγώ είμαι της άποψης ότι αν έχεις σωστό documentation επάνω στις μεθόδους , κάποιο εξωτερικό wiki κτλ. δεν χρειάζεται σχόλια μέσα στον κώδικα εκτός απο λίγες περιπτώσεις που μπορεί να χρειαστεί να κάνεις κάτι πολύπλοκο.

Ανάλογα με τον τρόπο προσέγγισης έχεις και διαφορετικό τρόπο γραφής.

Εσύ λές ας πούμε να ονομάσεις την μεταβλητή μες τον τρόπο που έγραψες παραπάνω

Εγώ ας πούμε μπορώ να σου πώ να φτιάξεις μία μέθοδο findTheMagicNumber(Person , Person) που θα έχει ένα σωστό documentation ,θα είναι δυναμικό και re usable και όταν του περνάς τον Jim και τον John θα σου επιστρέφει αυτό που θέλεις μέσα απο ένα decision table σε μία βάση.

Ναι 10 φορές μεγαλύτερη πολυπλοκότητα για ένα magic number , αλλά είναι καθαρό , reusable , δυναμικό και έτσι δεν θα χρειαστεί να γράψεις κανέναν σχόλιο

Ελπίζω να έπιασες τον τρόπο σκέψης μου , ε όλο αυτό μπορεί να γίνει στο μεγαλύτερο μέρος του κώδικα

Επίσης αρκετοί γράφουν μακαρόνια κώδικα και για αυτό γεμίζουν και με σχόλια

Αν έχεις την λογική να φτιάχνεις μεθόδους με 10-15 γραμμές , σωστά και κατανοητά ονόματα με documentation στην μέθοδο πάλι δεν έχεις ανάγκη απο σχόλια μέσα στον κώδικα

Για τον TS

Πολλοί από εμάς έχουμε περάσει από την φάση σου , εγώ προσωπικά πιστεύω ότι όλα αυτά συμβαίνουν όταν έχεις λάθος άτομα (managers) που κοιτάνε να σπρώξουν την μπιζνα και απλά τους ενδιαφέρει να πουλήσουν το προϊόν χωρίς να τους απασχολεί η ποιότητα του.

Εκεί θέλει διαφορετική προσέγγιση με νούμερα που να δείχνουν ότι όσο συνεχίζεις με αυτόν τον ρυθμό θα πέφτει η ποιότητα , απόδοση , εξέλιξη της εφαρμογής οπότε στο μέλλον θα αντιμετωπίσετε προβλήματα. 

Δυστυχώς δεν είναι δική σου δουλειά αν είσαι απλός προγραμματιστής να κάνεις κάτι περισσότερο από αυτό αν δεν έχεις άτομα σε υψηλότερες θέσεις που να καταλαβαίνουν.

Και εγώ έτσι ήμουν μία 4ετία και άλλαξα εταιρεία και ένιωθα ούγγανος.

Οπότε αν δεις ότι δεν την παλεύεις άλλο με αυτή την κατάσταση και δεν μπορείς να διορθώσεις κάτι , σιγά σιγά κοίτα να φύγεις για να μην μείνεις και εσύ στάσιμος

[Papakaliati]

11 λεπτά πριν, tsofras είπε

Όλα σχετικά είναι ρε μαν και εγώ είμαι της άποψης ότι αν έχεις σωστό documentation επάνω στις μεθόδους , κάποιο εξωτερικό wiki κτλ. δεν χρειάζεται σχόλια μέσα στον κώδικα εκτός απο λίγες περιπτώσεις που μπορεί να χρειαστεί να κάνεις κάτι πολύπλοκο.

Ανάλογα με τον τρόπο προσέγγισης έχεις και διαφορετικό τρόπο γραφής.

Εσύ λές ας πούμε να ονομάσεις την μεταβλητή μες τον τρόπο που έγραψες παραπάνω

Εγώ ας πούμε μπορώ να σου πώ να φτιάξεις μία μέθοδο findTheMagicNumber(Person , Person) που θα έχει ένα σωστό documentation ,θα είναι δυναμικό και re usable και όταν του περνάς τον Jim και τον John θα σου επιστρέφει αυτό που θέλεις μέσα απο ένα decision table σε μία βάση.

Ναι 10 φορές μεγαλύτερη πολυπλοκότητα για ένα magic number , αλλά είναι καθαρό , reusable , δυναμικό και έτσι δεν θα χρειαστεί να γράψεις κανέναν σχόλιο

Ελπίζω να έπιασες τον τρόπο σκέψης μου , ε όλο αυτό μπορεί να γίνει στο μεγαλύτερο μέρος του κώδικα

Επίσης αρκετοί γράφουν μακαρόνια κώδικα και για αυτό γεμίζουν και με σχόλια

Αν έχεις την λογική να φτιάχνεις μεθόδους με 10-15 γραμμές , σωστά και κατανοητά ονόματα με documentation στην μέθοδο πάλι δεν έχεις ανάγκη απο σχόλια μέσα στον κώδικα

Κάτσε, documentation πανω στις μεθοδους σαν σχολια τα αντιλαμβάνομαι προσωπικά, δεν διαφοροποιώ σε σχόλια στις μεθόδους, και σε σχόλια μέσα σε κώδικα. 

Και o Jim and John στην συγκεκριμένη περίπτωση είναι τα άτομα που αποφασίστηκε η τιμής της μεταβλητής, όχι μεταβλητές κάθε αυτές 😛 

Και δεν θα πρέπει να έχεις στόχο να φτιάχνεις δε και καλά 10-15 γραμμές μεθόδους, αλλά οσο χρειαστει αναλογα με το single responsibility principle. To να σπας μια μεθοδο 50 γραμμων που κανει ενα και μονο πραγμα, σε 5 μεθοδους των 10 γραμμων, δεν βοηθαει, αλλα μπερδευει. 

Εκεί που θέλω να καταλείξω, είναι ότι το να ακολουθείς τυφλά μια λογική, ποτέ δεν μπορεί να καταλήξει σε καλό. Πρέπει πάντα να παραμένεις  ευέλικτος και δεκτικός.

Επεξ/σία 9 Δεκεμβρίου 2020 από Papakaliati

[tsofras]

7 λεπτά πριν, Papakaliati είπε

Κάτσε, documentation πανω στις μεθοδους σαν σχολια τα αντιλαμβάνομαι προσωπικά, δεν διαφοροποιώ σε σχόλια στις μεθόδους, και σε σχόλια μέσα σε κώδικα. 

Και o Jim and John στην συγκεκριμένη περίπτωση είναι τα άτομα που αποφασίστηκε η τιμής της μεταβλητής, όχι μεταβλητές κάθε αυτές 😛 

Και δεν θα πρέπει να έχεις στόχο να φτιάχνεις δε και καλά 10-15 γραμμές μεθόδους, αλλά οσο χρειαστει αναλογα με το single responsibility principle. To να σπας μια μεθοδο 50 γραμμων που κανει ενα και μονο πραγμα, σε 5 μεθοδους των 10 γραμμων, δεν βοηθαει, αλλα μπερδευει. 

Ε όχι το documentation σε μία μέθοδο δεν είναι σχόλιο , είναι documentation 

Και εγώ για τα σχόλια στον κώδικα κατάλαβα ότι μιλάμε

Τώρα για τις γραμμές , απλά σου αναφέρω ότι διαβάζω τόσα χρόνια απο best practices και προσωπική εμπειρία . Σίγουρα μέθοδο με πάνω από 20 γραμμές δεν έχει τύχει να χρειάζομαι και είναι ευκολότερο να γράψεις το unit test και ακόμη και στο μάτι χωρίς να κάνεις scroll πάνω κάτω

Απλά μιλάω για την εμπειρία που έχω αποκτήσει εγώ μετά απο 20 κάτι χρόνια ενασχόλησης , δεν λέω ότι είναι αυτή η σωστή και καμία άλλη , απλά τυχαίνει την τελευταία 10ετία να έχουμε εξωτερική εταιρεία που να ελέγχει την ποιότητα κώδικα κάποιων εκατομμυρίων γραμμών οπότε θέλοντας και μη έχω μάθει να γράφω με συγκεκριμένο τρόπο

 

Επεξ/σία 9 Δεκεμβρίου 2020 από tsofras

[Dinos_12345]

Πάντως έχει σημασία και τι γράφεις και πως το γράφεις για το που θα βάλεις σχόλια. Πχ, αν γράψεις μια εφαρμογή Android με MVVM και χρησιμοποιήσεις Jetpack Components που είναι μια standard τεχνική για υλοποίηση εφαρμογών, δεν θες σχόλια σε πολλά σημεία που αν το δώσεις σε κάποιον που δεν γράφει έτσι την εφαρμογή, δεν θα καταλάβει τίποτα. 

Η λύση σου δεν είναι περίπλοκη και δεν χρειάζεται σχόλια, παρά μόνο σε σημεία που κάνεις κάτι που δεν είναι φως φανάρι, επειδή ο τρόπος που γράφεις την εφαρμογή είναι αυστηρά καθορισμένος και ακολουθεί πολλαπλές καλές πρακτικές που όλοι πρέπει να ακολουθούν ή να ξέρουν. 

Αν κάνεις κάτι που δεν ακολουθεί συγκεκριμένη ροή και κάποιο pattern, θες σαφώς περισσότερα σχόλια σε περισσότερα σημεία γιατί πρέπει να εξηγήσεις πως δένουν κάποια πράγματα μεταξύ τους. 

 

[smoipa]

Μια γνώμη και από εμένα. Σιχαίνομαι να βλέπω τον κώδικα μου να ξεπερνάει τις 40 - 50 γραμμές σε μία function, 9 στις 10 περιπτώσεις σημαίνει ότι κάπου το έχασα σχεδιαστικά. Προσπαθώ συνήθως να υπάρχει μια function που θα είναι ο σκελετός και το μόνο που θα κάνει είναι να καλεί άλλες και να μην κάνει κανέναν υπολογισμό η ίδια. Με αυτόν το τρόπο αν τα ονόματα που δίνεις στις επιμέρους function είναι self explanatory δεν νομίζω να έχεις κανένα θέμα, ή να χρειαστείς σχόλια. Από εκεί και πέρα όταν αλλάζεις κώδικα που ήδη υπάρχει για λόγους ιστορικότητας καλό είναι να μαρκάρεις τις αλλαγές που έκανες με το task και να γράφεις ένα μικρό documentation γιατί το έκανες. Για ενδεχόμενα roll back και τέτοια. Νομίζω είναι πολύ κουραστικός ένας κώδικας γεμάτος comment  και στο debug και στο development. Όσο αυξάνεται ένα object άρα και τα σχόλια από ένα σημείο και μετά δεν μπορείς ούτε να κάνεις scroll καλά καλά εκεί μέσα.
Όσον αφορά την αρχική ερώτηση του θέματος. Αν δεν υπάρχει κάποιος από τους από πάνω που να είναι διατεθειμένος να ασχοληθεί δεν μπορείς να κάνεις και πολλά, γιατί κανείς δεν σε λάβει στα υπόψιν του. Από εκεί και πέρα μπορείς είτε να κάνεις υπομονή, είτε να δεις αν στην εταιρεία σου μπορείς να πας σε κάποια άλλη ομάδα που να είναι καλύτερα ή ακόμα καλύτερα μόνος σου. Αλλιώς νομίζω είναι μονόδρομος η αλλαγή, αν όχι τώρα στα κοντά, τότε αργότερα.
Και έχεις δίκιο δεν μπορείς να δουλέψεις αποδοτικά για κανένα λόγο έτσι. Αλλά δυστυχώς δεν είναι στο χέρι σου.

[valkon]

Υπέροχος ο προγραμματισμός όταν το κάνεις για την πάρτυ σου, αλλά όταν μπλέκεσαι με τα πίτουρα...

[Επισκέπτης]

Είμαι υπέρ και προσπαθώ πάντα να γράφω clean (self-documented) κώδικα αλλά δυστυχώς δεν έχω ούτε την τεράστια εμπειρία αλλά ούτε γνωρίζω όλα τα best practices ώστε να συνδέω λογικές. Διαβάζοντας λοιπόν τις απαντήσεις περί κατηγορηματικής μη χρήσης σχολίων μου γεννήθηκαν οι εξής απορίες:

Γράφετε πάντα μόνοι σας; Σας ενδιαφέρει αν ο κώδικας σας μπορεί να συντηρηθεί από κάποιον άλλο π.χ. νέο στην εταιρεία που προσπαθεί να μπει στην ομάδα; Ο Product Owner / Project Manager / Team Leader σας είναι χαρούμενος όταν του παραδίδετε κομμάτια κώδικα χωρίς καθόλου σχόλια λέγοντας του απλά ότι θα βγάλει άκρη διαβάζοντας τα ονόματα των μεταβλητών / μεθόδων; Δεν έχει τύχει ποτέ να αναλάβετε κάτι από κάποιον άλλον και να μην βγάζετε άκρη με τις δίχως σχόλια "καλλιγραφίες" του.

Επεξ/σία 9 Δεκεμβρίου 2020 από Επισκέπτης