6. Development Policy

本章ではClimbLabを使って開発をおこなう場合の注意点について述べる．

新しく関数を作成したり機能を追加する場合は，次の取り決めを守っておこなう．基本的なコンセプトとして，シンプル，かつ今後も開発を続けやすいようにシミュレーションプラットフォームとしてのフォーマットを守り，かつ誰が読んでも読みやすく理解しやすいように書くことを心がける． 　このシミュレーションプラットフォームとしての理念を守ることは非常に重要であり，そのために重要なこととして，既存のmain_sim以外の歩行シミュレーション用Main関数は作成してはいけない．シミュレーションプラットフォームたる所以は，「1つのフレームワークで多様なシミュレーションが可能である」ことにあるため，そのフレームワークを増やしてはいけない．そのため，新たな関数や機能を作成する場合も，既存のmain_simに組み込む形で必ず実装する．

新しい機能を検証しながら実装する際，次の点に注意すると開発がスムーズに進むため，必要ではない設定はoffにするとよい． * dynamicsが必要でない場合は，dynamicsをoffにする * 歩行する必要がない場合，gait typeを’do_nothing’にする * シミュレーションを何秒も回す必要がない場合，シミュレーションの最大時間を0秒にする．

また，新しく関数を作る場合の関数の置き場所については，4章のフォルダ構成を参考に，共通した役割でくくられる適切なフォルダに置く． その時の，関数の命名方法について以下の点に注意する．

  • スネークケースを用いる

    ✕ updGiaCalculation.m

    〇 upd_gia_calulation.m

  • 関数名に大文字は使わない

    ✕ upd_GIA_calculation.m

    〇 upd_gia_calculation.m

  • 関数の接頭辞を，次の既存の関数の命名方法にのっとって採用する

    • config_: 2.4節参照．シミュレーションの設定に関わる関数．

    • ini_: 2.5節参照．ロボットやシミュレーション環境の初期設定に関わる関数

    • upd_: 2.6節参照．ループ内で，歩容や制御・力学に関わる関数

    • vis_: 2.7節参照．図の描画に関わる関数

    • sav_: 2.8節参照．シミュレーション履歴の保存に関わる関数

    • main_ : 3章参照．単体で実行してclimblabの開発に有用な関数に付ける

  • 関数の名前はどんなに長くなっても構わないので，その関数がどういう機能を有しているのか分かるように書く．

上記のルールにのっとって新しく関数を作成した後の，具体的なコードの記述ルールについて説明する．以降の内容は新たな機能の実装の際にも共通する注意事項である．

1. 新しい関数ファイルの冒頭にその関数の仕様について明確に記載する．

この冒頭の記述を読むだけで，その関数のおおまかな機能が把握できるようにする． 記述する項目は，

  • 関数のくくり(configuration/update/visualize/save/main)

  • 関数名

  • 関数の簡単な説明

  • 作成日時

  • 作成者

  • 最終編集日時

  • 最終編集者

  • 関数の詳細な説明

  • 出力変数の一覧と，各変数の簡単な説明

  • 入力変数の一覧と，各変数の簡単な説明

である．以下に記述例を示す．

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
%%%%%% Configuration
%%%%%% config_save_settings
%%%%%% 
%%%%%% Configure default saving settings
%%%%%% 
%%%%%% Created 2020-07-08
%%%%%% Warley Ribeiro
%%%%%% Last update: 2021-03-31
%%%%%% Keigo Haji
%
%
% Load default configurations for saving
%
% Function variables:
%
%     OUTPUT
%         save_settings: Data saving settings (struct)
%     INPUT
%         -


2. むやみにmain_sim内に新たな関数の記述を増やさず，main_sim内で実行されている既存の関数内に組み込む形で新たな機能を実装する．

これは，ClimbLabがシミュレーションプラットフォームとして機能していくためにmain_simの一般性を担保するためである．また，同時にmain_simを複数人が編集するとGitのmergeの際にconflictが発生しやすくなるので，その問題を避けるという目的もある． 悪い例）main_sim内に直接実装

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
MAIN_FILE.m
...
disp(time);
if gait_param.type = ‘new_gait’
new_gait(...)
else
path_planning_param = upd_path_planning(...);
end
[motion_planning_param, des_SV] = upd_motion_planning(...);
...

良い例）main_simはそのままに，upd関数内で場合分けをおこなっている

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
MAIN_FILE.m
...
disp(time);
path_planning_param = upd_path_planning(...);
[motion_planning_param, des_SV] = upd_motion_planning(...);
...
FUNCTION_FILE.m 

function path_planning_param = upd_path_planning(...)

switch gait_param.type
case ‘new_gait’
new_gait(...);
case ‘old_gait’
...


3. 変数はなるべくclassに収容する

大量のローカル変数を関数内でなるべく扱わないようにする．これはMATLABワークスペース内での変数の把握が難しくなるためである．変数の"くくり"を考えて，既存のclassにあてはまる場合は既存のclass(gait_planning_param,motion_planning_param等)に収容し，ない場合は自分の機能にあった新たなclassを作成すること． 悪い例）local変数が多い．

1
2
3
4
5
6
7
8
...
leg1_des_pos = …
leg2_des_pos = …
leg3_des_pos = …
leg4_des_pos = …
base_des_pos = ...
generate_trajectory(leg1_des_pos, leg2_des_pos, leg3_des_pos, leg4_des_pos, base_des_pos);
...

いい例）変数がclassに分類されている

1
2
3
4
5
...
path_planning_param.leg_des_pos = …
path_planning_param.base_des_pos = …
generate_trajectory(path_planning_param);
...


4. 変数名をわかりやすくつける

変数名はどんなに長くなってもいいので，誰にでもわかるように付ける．変数名の付け方は関数と同じく，snake_caseで統一し，camelCaseは使わない．また，その変数がどういう値を収容し，その単位(次元)はなんなのかをコメントで明記する． 悪い例）人が読んでも何の略称かわからない

1
2
3
4
5
...
L1 = …
WP.T = …
GPM = ...
...

いい例）コメントや変数名から何の値がどういう単位次元で収容されているか分かる

1
2
3
4
5
6
7
8
…
% Desired position of a leg [m]
motion_planning_param.des_leg_pos = …
% Period for crawl gait [s]
gait_parameter.T = …
% Grippable points [m]
surface_param.grippable_points = ...
...


5. 新しい機能の実装後は，必ず繰り返しテストをおこなう

新しい機能を実装した後は，パラメータや設定を変えてテストを繰り返し，バグが発生しないことを確かめてから上級生にReviewをお願いする．

6. 新しい機能の実装後は，既存のpresetでも実行し，問題がないことを確認する

新たな機能を実装したことで，これまのpresetが回らなくなったり，他の開発者の開発環境と干渉する恐れがあるため，config設定を既存のpresetにして全てのpresetを実行し，問題なく実行されることを確認する．

7. 関数を消さない

どんな関数であれ，むやみに削除しない．新たな機能によって，歩行が安定したり速くなったりするような何か結果がよくなる機能を実装したとしても，前まであった関数は絶対に削除しない．既存の関数は，これまでの財産であり，確実にこれまで稼動していたという点で非常に有用なものである．手法の比較をおこなう際や，またシンプルなアルゴリズムの方が理解しやすいという点で好まれ，必要とされる場合もある．それまでの関数を削除・更新するのではなく，新たな機能・ケースを追加するという点を意識し，既存の関数・新たな機能の両方が扱えるように開発を進める．

8. 他のメンバーも同時進行で開発していることを忘れない

ClimbLabは常に複数名が同時に開発をすすめている．そのため，自分が開発をしている間に，誰か他のメンバーが開発を終わらせて新機能を実装することがよく発生する．この際，developブランチのrebaseを常におこなうこと．自分が開発段階で採用していた関数が，他のメンバーの実装によって一部変更されている可能性があるため，常に他のメンバーの開発状況について把握する．一方で，当然，自分の実装が他のメンバーにも影響を与えるため，常に報告・連絡・相談を忘れない．

9. 自分のおこなった変更点をわかりやすくメンバーに共有する

上でも述べたとおり，自分の実装は他人の開発に影響を与える．そのため，何か新しい機能の開発を終えたら，その実装によってどんな点が変更されたのかを，その作業の当事者ではない他のメンバー達にもわかりやすく共有する．

10. 他のメンバーと疑問点・問題点を共有する

同じ疑問を他の開発メンバーも抱いていたり，もしくはすでに解決した経験があるかもしれない．または，その問題を解決するような機能を新たに別のメンバーが実装してくれるかもしれない．

11. 見つけたバグを報告する

開発中にバグを見つけたら，みんなに共有すること．すでに解決したと思われていたバグの発見や致命的な欠陥があるまま開発を進めないように，すぐに芽をつむ．