Comments 17
UFO just landed and posted this here
> Во-первых,
Можете показать хоть один более-менее большой проект, где хороший код полностью заменил бы документацию?
> Во-вторых
Смысл в том, чтобы было понятно, что это за число, а не ответить на все возможные вопросы относительно этого числа. Понятно, что если о конкретной переменной нужно знать больше, одни именем не обойдёшься — это нигде вроде и не утверждается.
Можете показать хоть один более-менее большой проект, где хороший код полностью заменил бы документацию?
> Во-вторых
Смысл в том, чтобы было понятно, что это за число, а не ответить на все возможные вопросы относительно этого числа. Понятно, что если о конкретной переменной нужно знать больше, одни именем не обойдёшься — это нигде вроде и не утверждается.
Во-вторых — пример в студию, где использование прямой константы в тексте оператора даст Вам ответ на все ниже-перечисленные вопросы.
Вроде у автора во первых строках повествования как раз это оговорено, если я правильно понял.
Ну типа не воспринимайте всё так буквально, ищите баланс, в этом основное искусство ремесла, так сказать.
Слова «самодокументируемый код» — это ещё один способ сказать «читаемый код». Сам по себе он не заменит настоящей документации или хороших комментариев, но с ними или без них определённо сделает вашу жизнь и жизнь ваших коллег проще.
Ну типа не воспринимайте всё так буквально, ищите баланс, в этом основное искусство ремесла, так сказать.
if (x < 23) плохо и if (x < maxClassSizeInPeoplePhysicalCapacityShouldBeMoreThan20) тоже не очень.
> смысл как раз что бы заменить.
Дурость полная.
Самый лучший, идеально написанный и толковый код может неплохо пояснить ЧТО он делает, но никогда не объяснит ПОЧЕМУ. Тут без документации никак не обойтись.
Например буквально вчера тут была статья про то, какие вроде бы полезные патчи к JDK отклонялись и почему. И без знания контекста принятия решений (который можно и нужно описывать отдельно, человеческим языком в комментариях и документации) вы будете смотреть на этот код — который как раз написан по всем стандартам, с короткими функциями, понятными именами и т.п. — и все равно не будете понимать, почему он работает именно так, а не иначе.
Дурость полная.
Самый лучший, идеально написанный и толковый код может неплохо пояснить ЧТО он делает, но никогда не объяснит ПОЧЕМУ. Тут без документации никак не обойтись.
Например буквально вчера тут была статья про то, какие вроде бы полезные патчи к JDK отклонялись и почему. И без знания контекста принятия решений (который можно и нужно описывать отдельно, человеческим языком в комментариях и документации) вы будете смотреть на этот код — который как раз написан по всем стандартам, с короткими функциями, понятными именами и т.п. — и все равно не будете понимать, почему он работает именно так, а не иначе.
Предложенное давным-давно известно — именно в изложенном контексте. Стоило ли печать?
Тем более даже литературный текст с непонятным контекстом требует (и имеет) комментарии.
Короче, на мой взгляд, набор переведенных банальных истин.
У множества мелких функций есть другой недостаток: за ними сложнее видеть алгоритм работы.
Когда всё написано максимально линейно, лишь с разделением на блоки, логика работы прослеживается чётко. Но если текст нарезан на мельчайшие функции, создаётся полное ощущение паззла, который вывалили перед вами россыпью. Каждый кусочек прост и понятен, а вот чтоб сложить цельную картину происходящего — ох как постараться надо.
Совсем хреново, если стыковка между функциями ещё и неявная, например в рантайме через всякие сервис-локаторы. Тогда без отладчика и вовсе не понять, что делает такой код.
Когда всё написано максимально линейно, лишь с разделением на блоки, логика работы прослеживается чётко. Но если текст нарезан на мельчайшие функции, создаётся полное ощущение паззла, который вывалили перед вами россыпью. Каждый кусочек прост и понятен, а вот чтоб сложить цельную картину происходящего — ох как постараться надо.
Совсем хреново, если стыковка между функциями ещё и неявная, например в рантайме через всякие сервис-локаторы. Тогда без отладчика и вовсе не понять, что делает такой код.
UFO just landed and posted this here
> У множества мелких функций есть другой недостаток: за ними сложнее видеть алгоритм работы.
Понимаете, а множество мелких функций — это и есть алгоритм работы.
Считаете, нет? Тогда встречный вопрос — гигантская функция, состоящая из ассемблерного кода, лучше? Она ведь явно показывает алгоритм работы, включая мельчайшие детали типа управления памятью. Вся картина происходящего перед глазами, так сказать. Но почему-то всю картину в голове уместить становится очень сложно.
А ларчик просто открывается: детализация алгоритма работы зависит от уровня абстракции, на котором вы находитесь. Если реализацию высокоуровневой функции можно записать с помощью нескольких понятных терминов, то всякие ещё более мелкие штуки вплоть до мельчайших типа управления памятью — это детали реализации для нынешнего уровня абстракции.
О них не нужно писать на высоком уровне абстракции, их, напротив, нужно прятать. А если они вам нужны, то вам на самом деле нужны не они, а нужен более низкий уровень абстракции, который находится в реализации одной из мелких функций.
А удобная IDE поможет быстро перейти к реализации интересующей мелкой функции.
Понимаете, а множество мелких функций — это и есть алгоритм работы.
Считаете, нет? Тогда встречный вопрос — гигантская функция, состоящая из ассемблерного кода, лучше? Она ведь явно показывает алгоритм работы, включая мельчайшие детали типа управления памятью. Вся картина происходящего перед глазами, так сказать. Но почему-то всю картину в голове уместить становится очень сложно.
А ларчик просто открывается: детализация алгоритма работы зависит от уровня абстракции, на котором вы находитесь. Если реализацию высокоуровневой функции можно записать с помощью нескольких понятных терминов, то всякие ещё более мелкие штуки вплоть до мельчайших типа управления памятью — это детали реализации для нынешнего уровня абстракции.
О них не нужно писать на высоком уровне абстракции, их, напротив, нужно прятать. А если они вам нужны, то вам на самом деле нужны не они, а нужен более низкий уровень абстракции, который находится в реализации одной из мелких функций.
А удобная IDE поможет быстро перейти к реализации интересующей мелкой функции.
Sign up to leave a comment.
Советы по написанию самодокументируемого кода