Создание хорошего описания к коду

#yii #структуры #проектирование #проекты

Как возник данный вопрос, я, наверное, уже перейду к сути. Есть запрос на сервак,
у него 26 параметров. (мило правда?) запросов к серваку примерно может быть около 350!
в каждом от 5 до кучи передаваемых параметров.
Смысл в следующем, вот и вопрос.
У меня каждый запрос разбит на свой Action каждый action лежит в отдельном файле
//upd_start
Почему выбрано именно разбиение actions на файлы. Проект достаточно большой. Чтобы
все разработчики не расширяли сам контроллер, а просто дописывали в него 1-2 строчки
для подключения нового экшена + удобно редактировать проект такими кусками, а не целым
файлом, который бы терпел изменения постоянно. По мне так это правильно.
//upd_end
пример:
public function actions()
     {
     /* All actions in this controller 
      * are located in folder 
      * application.controllers.frontend.requests
      */
     return array(
                  'gf' => 'application.controllers.frontend.requests.gf',
                   // и т.д.
                );
      }

Первый вопрос:

На каком языке писать описание ко всему проекту?

В данный момент пытаюсь описывать на ENG, как может быть заметно из вышеописанной
функции, описание на ENG.
В gf.php описание тоже на ENG
@NumSeats          - The total number of passengers for which availability is being
requested
 @StartDt           - Date of Departure or Arrival. 
 @StartPt           - Airport or city code of the customer embarkation.
 @EndPt             - Airport or city code of the customer Destination.
 @StartTm           - Requested departure in 24-hour clock

В принципе, считаю что это правильно! В плане разработки проекта другими участниками,
как русско, так и англо говорящими.
Но есть одно но. Есть люди в компании не особо понимающие ENG язык и тем самым просят
комментировать код на русском языке.
В чем прикол? Ну на русском читать ведь проще! Соглашусь, переводить технический
ENG это пипец как "весело", схожу потихонечку с ума + ко всему не всегда получается
правильно перевести ENG на RUS в связи с разными обстоятельствами (незнание каких-то
оборотов и т.д.) В общем хватает веселых вещей по языкам.
Есть варианты решения, забить на ENG писать только на RUS второе решение писать только
на ENG, третье писать в 2х вариантах и в ENG/RUS что решит траблы обоих случаев, но
увеличит кол-во описания к коду, что на мой взгляд не есть хорошо.
Вот на стадии проектирования проекта и хочу выяснить как лучше делать.
С одной стороны хочется доставить всем удовольствие от разработки и писать описание
для всех, все равно приходится переводить мануал системы на RUS, с другой стороны писать
описалово на 2х языках муторно и как-то по кол-ву кода в файле слишком много.
Будет ли большое описание влиять на производительность кода?
последнее редактирование - 11.06.2013 15:32
Будут дополнения озвучу, пока все.
Жду ваших интересных отзывов по теме. 
Естественно буду продолжать открывать новые вопросы по теме разработки.    

Ответы

Ответ 1

@Shrek, не очень понял, что это за люди, которые хотят на русском.
Если они будут сопровождать проект, то лучше делать комментарии на RUS.
Если же это кто-то просто из любопытных заказчиков, то как Вам удобней (видимо, оставьте
ENG).
А писать комментарии в 2-х вариантах, это ни к чему. Тогда уж лучше их вообще не
писать, т.к. через полгода один из вариантов точно уже не будет соответствовать коду.