Arduino Logic 101 | Μάθημα 5.3: Documentation (Γράφοντας κώδικα που καταλαβαίνουν και οι άλλοι)
Καλωσορίσατε στο Μάθημα 5.3! Στο προηγούμενο μάθημα αναλύσαμε τη διαφορά ανάμεσα στα συντακτικά και τα λογικά λάθη. Σήμερα κλείνουμε την πέμπτη ενότητα με το πιο υποτιμημένο, αλλά ίσως πιο σημαντικό εργαλείο ενός Software Engineer: την τεκμηρίωση κώδικα (Documentation).
Όταν δουλεύεις μόνος σου σε ένα μικρό project, είναι εύκολο να θυμάσαι τι κάνει η κάθε γραμμή. Τι γίνεται όμως όταν επιστρέψεις σε αυτόν τον κώδικα μετά από 6 μήνες; Ή τι συμβαίνει όταν είσαι μέλος μιας ομάδας, όπως η Unique Tech, όπου έξι διαφορετικά άτομα πρέπει να συνεργαστούν για να λειτουργήσει το ίδιο βιο-ρομποτικό σύστημα;
Χωρίς σωστό documentation, ο κώδικας μετατρέπεται γρήγορα σε "ιερογλυφικά". Ας δούμε πώς μπορούμε να το αποφύγουμε αυτό με 3 απλά βήματα!
1. 💬 Η Δύναμη των Σχολίων (Comments)
Τα σχόλια είναι σημειώσεις που γράφουμε μέσα στον κώδικα για να εξηγήσουμε τη λογική μας. Ο μεταγλωττιστής (compiler) του Arduino αγνοεί πλήρως τα σχόλια, πράγμα που σημαίνει ότι δεν πιάνουν καθόλου χώρο στη μνήμη της πλακέτας μας και δεν επηρεάζουν την ταχύτητα εκτέλεσης.
Στη C++ (και άρα στο Arduino IDE) έχουμε δύο τρόπους να γράψουμε σχόλια:
Σχόλια μίας γραμμής: Χρησιμοποιούμε τη διπλή κάθετο (
//). Ό,τι γράψουμε μετά από αυτήν μέχρι το τέλος της γραμμής θεωρείται σχόλιο.Σχόλια πολλών γραμμών: Ξεκινάμε με
/*και κλείνουμε με*/. Είναι ιδανικά για την εισαγωγή ενός αρχείου ή για μεγάλες επεξηγήσεις.
/*
* Unique Tech - Bio-Robotic System v1.0
* Συγγραφέας: Ομάδα Ανάπτυξης Λογισμικού (Unique Tech)
* Περιγραφή: Έλεγχος ποιότητας αέρα στην τάξη και XAI ανάλυση.
*/
int co2Pin = A0; // Ο αισθητήρας CO2 είναι συνδεδεμένος στην αναλογική θύρα A0
2. 🏷️ Ονοματολογία με Νόημα (Meaningful Naming)
Ένα από τα μεγαλύτερα μυστικά του καλού documentation είναι να γράφεις κώδικα που "αυτο-εξηγείται". Αυτό το πετυχαίνουμε δίνοντας έξυπνα και περιγραφικά ονόματα στις μεταβλητές και τις συναρτήσεις μας, αντί για τυχαία γράμματα όπως x, y, a.
Δείτε τη διαφορά:
Δυσνόητος κώδικας:
int x = 420; if (x > 1000) { digitalWrite(13, HIGH); }Καθαρός κώδικας (Self-Documenting):
int co2LevelPpm = 420; int co2MaxThreshold = 1000; int ledRedAlertPin = 13; if (co2LevelPpm > co2MaxThreshold) { digitalWrite(ledRedAlertPin, HIGH); }
Στο δεύτερο παράδειγμα, ακόμα κι αν κάποιος δεν γνωρίζει καθόλου ρομποτική, καταλαβαίνει αμέσως ότι αν η συγκέντρωση
3. 📝 Η Δομή «Header» στην αρχή του αρχείου
Κάθε επαγγελματικό πρόγραμμα ξεκινάει με ένα σύντομο κείμενο (Header) στην κορυφή. Αυτό βοηθάει οποιονδήποτε ανοίξει το αρχείο να καταλάβει αμέσως:
Ποιος έγραψε τον κώδικα.
Πότε γράφτηκε ή τροποποιήθηκε τελευταία φορά.
Ποιος είναι ο σκοπός του προγράμματος.
Ποιες θύρες (pins) του Arduino πρέπει να συνδεθούν στο hardware.
🎓 Έρχεται το Μεγάλο Quiz & η Πιστοποίηση (Certification)!
Με το μάθημα αυτό ολοκληρώσαμε επίσημα την ύλη του Arduino Logic 101: Σκέψου σαν Μηχανικός Λογισμικού! Περάσαμε μαζί από τη νοοτροπία των μηχανών, τις μεταβλητές, τις αποφάσεις, τις επαναλήψεις και, τέλος, το debugging και την οργάνωση του κώδικα.
Τι ακολουθεί τώρα;
Τις επόμενες ημέρες θα δημοσιεύσουμε εδώ στο blog της Unique Tech ένα σύντομο, online Quiz που θα τεστάρει τις γνώσεις σας σε όλα όσα μάθαμε σε αυτές τις 5 ενότητες.
🏆 Unique Tech Certification: Όσοι απαντήσουν σωστά στις ερωτήσεις του quiz, θα λάβουν εντελώς δωρεάν ένα ψηφιακό πιστοποιητικό παρακολούθησης από τη Unique Tech για να το μοιραστούν με τους φίλους τους ή να το προσθέσουν στο μαθητικό τους portfolio!
Μείνετε συντονισμένοι, κάντε μια γρήγορη επανάληψη στα προηγούμενα μαθήματα και ετοιμαστείτε να αποδείξετε ότι πλέον σκέφτεστε σαν πραγματικοί μηχανικοί λογισμικού!
Έχετε απορίες για τα σχόλια, το documentation ή το επερχόμενο quiz; Γράψτε μας στα σχόλια και η ομάδα μας θα σας απαντήσει αμέσως!
#UniqueTech #ArduinoLogic101 #CleanCode #CodeDocumentation #STEMGreece #ArduinoCertification #RoboticsKids
Σχόλια
Δημοσίευση σχολίου