ну
- код должен быть самоописательным
- редкие сложные куски кода можно снабдить комментом, но это обычно очень маленькая часть, и не стоит даже времени заводить всю шарманку
- документация к апишке всеравно пишется руками со ссылками и примерами кода, так что голосом не надиктуешь