Main logo www.4project.co.il
כל הרכיבים לפרוייקט שלכם
עגלת קניות

העגלה ריקה

האם המוצר במלאי?
[X]
עמוד המוצר מציג את רמת המלאי האמיתית, הזמינה במחסנינו בישראל.
פרטים נוספים
איך מזמינים ומשלמים?
[X]
ההזמנה והתשלום מתבצעים רק דרך האתר.
איסוף או משלוח? כמה זה יעלה?
[X]
האתר מציע 5 אפשרויות משלוח וגם אפשרות לאיסוף עצמי מהמחסן.
אחרי הוספת המוצרים לעגלת הקניות, אפשר לראות בה את האפשרויות, המחירים והערכת זמני הגעת המשלוח.
המחיר יחושב לפי גודל ומשקל המוצרים שבחרת.
פרטים נוספים
מתי ההזמנה מוכנה?
[X]
אין צורך לעדכן אותנו טלפונית על ביצוע ההזמנה. אנו רואים אותה מיד ומטפלים בה במהירות.
כמה מהר? לפי הסטטיסטיקה של 3 חודשים האחרונים, הכוללים גם חגים וחופשים, הזמנות שבוצעו בשעות אלה (יום שלישי בין השעות 23 ל-24) היו מוכנות תוך 8 שעות ו-44 דקות.
פרטים נוספים
ייצור ושירותים
מחלקות מוצרים

מדריך: סגנון הכתיבה ל-Arduino

על ידי Alex » ב' ספטמבר 18, 2017 3:35 pm
זהו מדריך לכתיבת דוגמאות ל-Arduino כך שהן תהיינה ברורות גם למתחילים וגם למתקדמים. אתם לא חייבים לכתוב את הקוד בדיוק באותה הדרך, אבל זה יכול לעזור אם אתם רוצים שהקוד יהיה ברור לכל הרמות של המשתמשים. אלה לא חוקים מוצקים ומהירים, אלא יותר אוסף של הנחיות. חלק מההנחיות כנראה מנוגדות אחת לשניה, השתמשו בהגיון שלכם כדי להחליט לאיזו מהן עדיף להיצמד. אם אתם לא בטוחים, תשאלו מישהו שאמור ללמוד ממה שאתם כותבים מה נראה להם הגיוני יותר. רצוי לקרוא גם מדריך: סגנון ה-API בכתיבת ספריות.

כתיבת מדריך
(רוב הדברים כאן נאספו לאורך השנים מעורכים שונים)

השתמשו בצורת כתיבה פעילה, כמו למשל "משה כתב את הקוד" מאשר "הקוד נכתב ע"י משה".

כתבו בצורה ברורה ושוטפת, כאילו שהאדם שאמור לבצע את ההנחיות שלכם נמצא מולכם בחדר.

כשאתם נותנים הנחיות, השתמשו בגוף שני, כך שהקורא יבין שהוא זה שאמור לבצע אותם.

השתמשו במשפטים ופקודות קצרים, פשוטים והצהרתיים מאשר במשפטים מורכבים וארוכים. לקורא יהיה קל יותר לעכל הוראה אחת בכל פעם.

תנו הנחיות בצורה ברורה, כמו:
"אחרי זה אתם קוראים את החישן..."
"תגדירו משתנה בשם..."

הימנעו ממשפטים שלא מוסיפים מידע. אל תגידו לקורא "אתה רוצה להגדיר את הקווים", אלא פשוט תגידו לו "תגדיר את הקווים".

השתמשו בתמונות ושרטוטים מאשר רק בשרטוט בלבד. הרבה חובבים לא יודעים איך לקרוא את השרטוטים.

בדקו את כל ההנחות שלכם. האם הקורא יבין את כל המושגים במדריך שלכם? אם לא, תסבירו אותם או תקשרו למדריך אחר שמסביר.

הסבירו את הרעיון הכללי, כך שהקורא יבין את התמונה הגדולה של מה שהוא הולך לעשות. אחרי זה תדריכו איך להשתמש בזה צעד אחר צעד.

כשאתם משתמשים במושג טכני בפעם הראשונה, תסבירו אותו. בקשו ממישהו שיעבור על המדריך ויבדוק שהסברתם את כל המושגים החדשים. יש סיכוי שפספסתם אחד או שניים.

תהיו עקביים עם המושגים שאתם משתמשים. אם אתם מתייחסים לרכיב או רעיון כלשהו לפי שם חדש, תסבירו את הקשר למושג האחר בצורה מפורשת. אל תחליפו בין שני מושגים לאותו הדבר, אלא אם אתם מסבירים לקורא שזהו אותו הדבר.

אל תשתמשו בראשי תיבות או קיצורים לפני שאייתתם אותם.

תגרמו לדוגמה שלכם לעשות משהו אחד כמו שצריך. אל תשלבו רעיונות או פונקציות, אלא אם המדריך הוא על שילוב הרעיונות.


כתיבת קוד לדוגמה
יעילות היא לא הפסגה, הקריאות כן.

המשתמשים החשובים ביותר ל-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.