tag:blogger.com,1999:blog-5830860775515675394.post4292105142663192661..comments2023-10-20T05:10:00.228-07:00Comments on Andrei Solntsev: Why the devil invented javadoc?asolntsevhttp://www.blogger.com/profile/16632087166612261207noreply@blogger.comBlogger3125tag:blogger.com,1999:blog-5830860775515675394.post-48613932731865814152011-05-03T23:38:57.500-07:002011-05-03T23:38:57.500-07:00Вот почему важно делать Code Reviews и писать Java...Вот почему важно делать Code Reviews и писать Javadoc корректно!<br /><br />Я с вами абсолютно согласен по поводу:<br /><br />Well documented code + meaningful tests - это практически всё, о чём девелопер может мечтать.<br /><br />К сожалению, пример Javadoc в статье приведён довольно хилый - это практически "только что сгенерированный стаб", дополненный одной срочкой - в большинстве организаций так его никто бы не написал*.<br /><br />* По крайней мене я на это надеюсь.<br />* По крайней мере я такого часто не встречал, а когда встречал, то такой коммит не прошёл бы Code Review.<br /><br />Поэтому, адресуя отмеченные вами четыре поинта:<br /><br />1) Одна из вещей на которую ревьюеры смотрят когда делают Code Reviews - это documentation update если надо.<br /><br />2) То, что эта приведённая в пример Javadoc не описывает ничего - проблема девелопера и ревьюера. Это обязанность девелопера обновить документацию к изменённой функциональности.<br /><br />Если и девелоперу и ревьюеру на это по барабану, то это уже другая история.<br /><br />Особенно важно, когда различные команды работают in the same space и которым поневоле приходится использовать API друг друга.<br /><br />Но и когда всё пишется внутри одной организации, я всё равно не вижу смысле не документировать код по нормальному.<br /><br />3) См. №2.<br /><br />4) Не понимаю поинта. Если правильно написать meaningful javadoc, то, поверьте, место, которое оно будет занимать будет волновать вас меньше всего.<br /><br />В добавок к вышесказанному:<br /><br />приведённый метод является довольно интуитивно понятный. Интуитивно понимать без докумментации бывает не всегда возможным - даже когда метод именован в соответствии с его функциональностью.<br /><br />javadoc обязателен.<br /><br />По поводу тестов - это так же одна из вещей, на которую смотрит ревьювер.<br /><br />Ну а уж если девелоперы не хотят писать javadoc, а ревьюеры не хотят по нормальному делать обзор комммитов, то я уверен и тесты писаться не будут.Dimonhttps://www.blogger.com/profile/08108449374300547198noreply@blogger.comtag:blogger.com,1999:blog-5830860775515675394.post-27436731704105729492010-05-17T07:16:36.483-07:002010-05-17T07:16:36.483-07:00@John Mercier
John, you are right: source code is ...@John Mercier<br />John, you are right: source code is not always available, and javadoc is still useful for public APIs.<br /><br />I am talking more about code which is created and used within the same company.asolntsevhttps://www.blogger.com/profile/16632087166612261207noreply@blogger.comtag:blogger.com,1999:blog-5830860775515675394.post-6743896305666889332010-05-16T19:28:14.475-07:002010-05-16T19:28:14.475-07:00If your code is cohesive you probably won't ha...If your code is cohesive you probably won't have to change the api or the documentation. There are also many cases where documentation is unavoidable. What if the user doesn't have access to the code? And I'm sure you look at the code for the java api rather than just look at the javadoc.Anonymoushttps://www.blogger.com/profile/15995318225144310283noreply@blogger.com