כתיבת מדריך
(רוב הדברים כאן נאספו לאורך השנים מעורכים שונים)השתמשו בצורת כתיבה פעילה, כמו למשל "משה כתב את הקוד" מאשר "הקוד נכתב ע"י משה".
כתבו בצורה ברורה ושוטפת, כאילו שהאדם שאמור לבצע את ההנחיות שלכם נמצא מולכם בחדר.
כשאתם נותנים הנחיות, השתמשו בגוף שני, כך שהקורא יבין שהוא זה שאמור לבצע אותם.
השתמשו במשפטים ופקודות קצרים, פשוטים והצהרתיים מאשר במשפטים מורכבים וארוכים. לקורא יהיה קל יותר לעכל הוראה אחת בכל פעם.
תנו הנחיות בצורה ברורה, כמו:
"אחרי זה אתם קוראים את החיישן..."
"תגדירו משתנה בשם..."
הימנעו ממשפטים שלא מוסיפים מידע. אל תגידו לקורא "אתה רוצה להגדיר את הקווים", אלא פשוט תגידו לו "תגדיר את הקווים".
השתמשו בתמונות ושרטוטים מאשר רק בשרטוט בלבד. הרבה חובבים לא יודעים איך לקרוא את השרטוטים.
בדקו את כל ההנחות שלכם. האם הקורא יבין את כל המושגים במדריך שלכם? אם לא, תסבירו אותם או תקשרו למדריך אחר שמסביר.
הסבירו את הרעיון הכללי, כך שהקורא יבין את התמונה הגדולה של מה שהוא הולך לעשות. אחרי זה תדריכו איך להשתמש בזה צעד אחר צעד.
כשאתם משתמשים במושג טכני בפעם הראשונה, תסבירו אותו. בקשו ממישהו שיעבור על המדריך ויבדוק שהסברתם את כל המושגים החדשים. יש סיכוי שפספסתם אחד או שניים.
תהיו עקביים עם המושגים שאתם משתמשים. אם אתם מתייחסים לרכיב או רעיון כלשהו לפי שם חדש, תסבירו את הקשר למושג האחר בצורה מפורשת. אל תחליפו בין שני מושגים לאותו הדבר, אלא אם אתם מסבירים לקורא שזהו אותו הדבר.
אל תשתמשו בראשי תיבות או קיצורים לפני שאייתתם אותם.
תגרמו לדוגמה שלכם לעשות משהו אחד כמו שצריך. אל תשלבו רעיונות או פונקציות, אלא אם המדריך הוא על שילוב הרעיונות.
כתיבת קוד לדוגמה
יעילות היא לא הפסגה, הקריאות כן.המשתמשים החשובים ביותר ל-Arduino הם מתחילים ואנשים שהקוד לא ממש חשוב להם, מה שכן חשוב הוא שהפרויקט יעבוד.
תהיו סלחניים לאנשים שמבינים בתכנות פחות מכם. אל תחשבו שהם חייבים להבין את המושגים הטכניים. הם לא, וזה לא הופך אותם לטיפשים. הקוד שלכם צריך להסביר את עצמו, או שתשתמשו בהערות כדי לעשות זאת. אם הרעיון דורש משהו מסובך כמו רגיסטרים, פסיקות או מצביעים, או שתסבירו את זה היטב, או שדלגו על זה.
אם אתם נדרשים לבחור בין גישה טכנית קלה להבנה או גישה היעילה ביותר, בחרו בראשונה.
הציגו מושגים רק כשהם שימושיים לדוגמה. השתדלו להקטין את כמות המושגים שאתם מציגים בכל דוגמה. לדוגמה, בתחילת ההסבר אפשר להסביר רק את הפונקציות הפשוטות עם משתנים מסוג
int בלבד וללא הגדרת קבועים שמייצגים את מספרי הקווים. מצד שני, בדוגמאות קצת יותר מתקדמות תוכלו להציג את הרעיונות הכלליים יותר ואיך הם יכולים להיות שימושיים. כיוונים כמו שימוש ב-const כדי להגדיר קווים או שימוש ב-byte במקום int למספרים בתחום בין ה-0 ל-255 הוא חשוב, אבל לא מחייב כדי להתחיל, כך שתנסו למזער אותם ודאגו להסביר אותם היטב כשהכיוון חדש לתוכנית ההסברים שלכם.מקמו את הפונקציות
()setup ו-()loop ותחילת התוכנית. הם עוזרים למתחילים לקבל סקירה כללית של התוכנית מכיוון שכל שאר הפונקציות נקראות מהן.הערות בקוד
הוסיפו הערה לכל הגדרת משתנה או קבוע עם תיאור של מה המשתנה עושה.
הוסיפו הערות לכל בלוק של קוד. אם אפשר, עשו זאת לפני הבלוק כדי שהקורא ידע מה הולך להגיע בהמשך.
הוסיפו הערות לכל לולאה.
השתמשו בפקודות
if מפורטות. כדי להקל על הקורא תגדירו בלוק (סוגריים מסולסלים) לכל דבר. הימנעו מהגדרה כזו:- קוד: בחר הכל
if (somethingIsTrue) doSomething;
במקומה השתמשו בכזו:
- קוד: בחר הכל
if (somethingIsTrue == TRUE) {
doSomething;
}
הימנעו ממצביעים (pointers).
הימנעו מ-
define#.משתנים
הימנו משמות המשתנים בעלי אות אחת. בחרו בשמות תיאוריים יותר.
הימנעו משמות משתנים כמו
val או pin. תהיו יותר תיאוריים, כמו למשל buttonState או switchPin.אם אתם רוצים להגדיר שמות למספר קו או כמות שלא תשתנה במהלך התוכנית, השתמשו ב-
const int. גישו זו פחות בעייתית מאשר define#, אבל עדיין מאפשרת ללמד את ההבדל בין משתנה לקבוע.השתמשו בסוגי משתנים בסגנון Wiring/Processing, כלומר:boolean ,char ,byte ,int ,unsigned int ,long ,unsigned long ,float ,double ,string ,array ,void במקום uint8_t וכו'. סגנון של Wiring/Processing יותר מסביר את עצמו ופחות מקוצר.
הימנעו מסגנון ממוספר שמבלבל את המשתמשים, כמו למשל:
- קוד: בחר הכל
pin1 = 2
pin2 = 3
etc.
אם אתם צריכים למספר מחדש ערכים (קווים למשל), תשקלו להשתמש במערך:
- קוד: בחר הכל
int myPins[] = { 2, 7, 6, 5, 4, 3 };
גישה זו מאפשרת להתייחס למספר הקו החדש ע"י מערך של ערכים:
- קוד: בחר הכל
digitalWrite(myPins[1], HIGH); // turns on pin 7
זה גם מאפשר להדליק או לכבות את כל הקווים בסדר שתרצו:
- קוד: בחר הכל
for (int thisPin = 0; thisPin < 6; thisPin++) {
digitalWrite(myPins[thisPin], HIGH);
delay(500);
digitalWrite(myPins[thisPin], LOW);
delay(500);
}
תחילה תסבירו את הקוד
הנה דוגמה טובה לכותרת:- קוד: בחר הכל
/*
Sketch title
Describe what it does in layman's terms. Refer to the components
attached to the various pins.
The circuit:
* list the components attached to each input
* list the components attached to each output
Created day month year
By author's name
Modified day month year
By author's name
http://url/of/online/tutorial.cc
*/
מעגלים
במפסקים/כפתורים המשמשים כקלט דיגיטלי, ברירת המחדל הוא שימוש בנגד pull-down ולא pull-up. בדרך זו הלוגיקה של השימוש במפסק נראית הגיונית יותר למי שלא מהנדס.שמרו על הפשטות של המעגל שלכם. לדוגמה, קבלי bypass הם שימושיים מאד, אבל רוב המעגלים הפשוטים יעבדו גם בלעדיהם. אם הרכיב במעגל הוא משני, הסבירו זאת למשתמש.
ראו גם:
פירוט שפת תכנות לסביבת Arduinoעמוד זה הוא תרגום של Arduino style guide לפי רישיון Creative Commons Attribution-ShareAlike 3.0.