32.1. Неофициальные рекомендации по оформлению сценариев

Опубликовано Bash в Ср, 23/12/2009 - 21:04

  • Комментируйте свой код. Это сделает ваши сценарии понятнее для других, и более простыми, в обслуживании, для вас.

    1. PASS="$PASS${MATRIX:$(($RANDOM%${#MATRIX})):1}"
    2. # Эта строка имела некоторый смысл в момент написания,
    3. # но через год-другой будет очень тяжело вспомнить — что она делает.
    4. # (Из сценария "pw.sh", автор: Antek Sawicki)


    Добавляйте заголовочные комментарии в начале сценария и перед функциями.

    1. #!/bin/bash
    2. #************************************************#
    3. #                   xyz.sh                       #
    4. #             автор: Bozo Bozeman                #
    5. #                Июль 05, 2001                   #
    6. #                                                #
    7. #          Удаление файлов проекта.              #
    8. #************************************************#
    9. BADDIR=65                       # Нет такого каталога.
    10. projectdir=/home/bozo/projects  # Каталог проекта.
    11. # ------------------------------------------------------- #
    12. # cleanup_pfiles ()                                       #
    13. # Удаляет все файлы в заданном каталоге.                  #
    14. # Параметры: $target_directory                            #
    15. # Возвращаемое значение: 0 — в случае успеха,            #
    16. #                        $BADDIR — в случае ошибки.      #
    17. # ------------------------------------------------------- #
    18. cleanup_pfiles ()
    19. {
    20.   if [ ! -d "$1" ]  # Проверка существования заданного каталога.
    21.   then
    22.     echo "$1 — не является каталогом."
    23.     return $BADDIR
    24.   fi
    25.   rm -f "$1"/*
    26.   return 0   # Успешное завершение функции.
    27. }
    28. cleanup_pfiles $projectdir
    29. exit 0
    Не забывайте начинать ваш сценарий с sha-bang -- #!/bin/bash.

  • Заменяйте повторяющиеся значения константами. Это сделает ваш сценарий более простым для понимания и позволит вносить изменения, не опасаясь за его работоспособность.

    1. if [ -f /var/log/messages ]
    2. then
    3.   ...
    4. fi
    5. # Представьте себе, что через пару лет
    6. # вы захотите изменить /var/log/messages на /var/log/syslog.
    7. # Тогда вам придется отыскать все строки,
    8. # содержащие /var/log/messages, и заменить их на /var/log/syslog.
    9. # И проверить несколько раз — не пропустили ли что-нибудь.
    10. # Использование "констант" дает лучший способ:
    11. LOGFILE=/var/log/messages  # Если и придется изменить, то только в этой строке.
    12. if [ -f "$LOGFILE" ]
    13. then
    14.   ...
    15. fi


  • В качестве имен переменных и функций выбирайте осмысленные названия.

    1. fl=`ls -al $dirname`                 # Не очень удачное имя переменной.
    2. file_listing=`ls -al $dirname`       # Уже лучше.
    3. MAXVAL=10   # Пишите имена констант в верхнем регистре.
    4. while [ "$index" -le "$MAXVAL" ]
    5. ...
    6. E_NOTFOUND=75                        # Имена кодов ошибок — в верхнем регистре,
    7.                                      # к тому же, их желательно дополнять префиксом "E_".
    8. if [ ! -e "$filename" ]
    9. then
    10.   echo "Файл $filename не найден."
    11.   exit $E_NOTFOUND
    12. fi
    13. MAIL_DIRECTORY=/var/spool/mail/bozo  # Имена переменных окружения
    14.                                      # так же желательно записывать символами
    15.                                      # в верхнем регистре.
    16. export MAIL_DIRECTORY
    17. GetAnswer ()                         # Смешивание символов верхнего и нижнего решистров
    18.                                      # удобно использовать для имен функций.
    19. {
    20.   prompt=$1
    21.   echo -n $prompt
    22.   read answer
    23.   return $answer
    24. }
    25. GetAnswer "Ваше любимое число? "
    26. favorite_number=$?
    27. echo $favorite_number
    28. _uservariable=23                     # Допустимо, но не рекомендуется.
    29. # Желательно, чтобы пользовательские переменные не начинались с символа подчеркивания.
    30. # Так обычно начинаются системные переменные.


  • Используйте смысловые имена для кодов завершения.

    1. E_WRONG_ARGS=65
    2. ...
    3. ...
    4. exit $E_WRONG_ARGS
    См. так же Приложение D.

  • Разделяйте большие сложные сценарии на серию более коротких и простых модулей. Пользуйтесь функциями. См. Пример 34-4.

  • Не пользуйтесь сложными конструкциями, если их можно заменить простыми.

    1. COMMAND
    2. if [ $? -eq 0 ]
    3. ...
    4. # Избыточно и неинтуитивно.
    5. if COMMAND
    6. ...
    7. # Более понятно и коротко.


 

... читая исходные тексты сценариев на Bourne shell (/bin/sh). Я был потрясен тем, насколько непонятно и загадочно могут выглядеть очень простые алгоритмы из-за неправильного оформления кода. Я не раз спрашивал себя: "Неужели кто-то может гордиться таким кодом?"
  Landon Noll