Чому не існує оглядів коду для проектів з відкритим кодом? [зачинено]

Там є дуже складні проекти з відкритим кодом, і для деяких з них я думаю, що я міг би внести певний внесок, і я хотів би, що міг, але перешкода для входу є занадто високою з єдиної причини: для зміни одного рядка коду на великий проект, ви мусите все це зрозуміти.

Вам не потрібно читати весь код (навіть якщо ви читаєте, його буде недостатньо) і розуміти все, що робить кожен рядок, і чому, тому що код, ймовірно, модулюється і розділяється, тому на місці є абстракції, але навіть тоді вам потрібно оглянути проект, щоб ви могли знати, де знаходяться модулі, де один модуль взаємодіє з іншим, що саме робить кожен модуль і чому , і в яких каталогах та файлах відбувається кожне з цих речей.

Я називаю цей огляд коду , як назва розділу, який можуть мати проекти з відкритим кодом на веб-сайті або документації, що пояснює їх код стороннім особам. Я думаю, що це піде на користь потенційним учасникам , оскільки вони зможуть визначити місця, де вони могли б будувати, фактичні первинні кодери, які братимуть участь у роботі, як вони могли б, написавши все, реорганізувати свій розум та допомогти користувачам , як вони допоможіть зрозуміти та краще повідомити про помилки, які вони відчувають, а може навіть стати учасниками.

Але все ще я жодного разу не бачив жодного з цих "оглядів коду". Чому? Чи є подібні речі, і я їх пропускаю? Речі, які виконують ту саму роботу, як я описав? Або це абсолютно марна ідея, оскільки всі, крім мене, легко розуміють проекти з тисячами рядків коду?

Тому що додаткові зусилля для створення та підтримки такого документа, і занадто багато людей не розуміють супутніх переваг.

Багато програмістів не є хорошими технічними письменниками (хоча багато); вони рідко пишуть документи строго для споживання людиною, тому не мають практики і не люблять це робити. Написання огляду коду вимагає часу, який ви не можете витратити на кодування, і початкова користь для проекту завжди більша, якщо ви можете сказати "Ми підтримуємо всі три варіанти кодування", а не "У нас дійсно чіткі пояснення нашого коду!" Думка про те, що такий документ приверне більше розробників, так що в кінцевому рахунку більше коду буде записано не зовсім чуже для них, але він сприймається як невизначена гра; чи справді цей текст змінить різницю між співавтором чи ні? Якщо я продовжую кодувати зараз , закінчіть цю справу.

Документ з оглядом коду також може змусити людей відчувати себе захищеними; важко описати рішення вищого рівня, не відчуваючи необхідності їх виправдовувати, і дуже часто люди приймають рішення без причини, яка "звучить досить добре", коли насправді написана власноруч. Також є ефект, пов'язаний із вищезгаданим: оскільки оновлення тексту відповідно до змінного коду спричиняє додаткові зусилля, це може перешкодити широким змінам коду. Іноді ця стабільність є хорошою справою, але якщо код дійсно потребує перезапису середнього рівня, це перетворюється на відповідальність.

Суха сувора правда?

Документація не робиться, оскільки проекти можуть обійтися без неї.

Навіть проекти з відкритим кодом часто стикаються з жорсткою конкуренцією. Більшість таких проектів починаються з великих плечей, вони починають яскраву ідею, часто яскраву ідею для чоловіка.

Таким чином, вони не можуть дозволити собі час та витрати на наймання людських документообігів, навіть якщо вони запропонували співпрацювати безкоштовно. Задокументований проект, інфакт, зазвичай спочатку пройшов кілька початкових ітерацій. Часто це починається з 1-3, можливо, 5 хлопців записують свою ідею роману і показують її світові як доказ концепції. Якщо ідея виявиться хорошою, тоді "послідовники" можуть додати, вони, як правило, починають просити розширення, нові параметри, переклади ... На даний момент код все ще є прототипом, як правило, із жорстко кодованими параметрами та повідомленнями.

Не всі проекти з відкритим кодом виходять за рамки цієї фази, лише ті, що руйнують "критичну масу", необхідні для залучення громадського інтересу. Більше того, одному з початківців розробників доводиться «думати велико і далеко» і планувати розширення тощо. Він також може стати проектом "євангеліста", а іноді і "керівником проекту" (інколи це різні люди). Це необхідний крок для налагодження проекту - від доведення концепції до встановленої галуззю реальності.

Вже тоді керівник проекту може вирішити не створювати документацію.

Динамічний, зростаючий проект буде як уповільненим, так і документація дійсно відставатиме від коду, в той час як він вдосконалюється дуже важко, впроваджувати переклади, параметри, підключати менеджерів ...

Зазвичай це:

1. Складено короткий вступний документ про те, що таке проект і куди він рухається (знаменита «дорожня карта»).
2. Якщо можливо, розробляється API, і він обирається як "задокументований код" на більшій частині основного коду.
3. Зокрема, API, а також інший код переформатуються та додаються спеціальні коментарі "PHPdoc" / "Javadoc" тощо. Вони пропонують гідний компроміс між витраченим часом та винагородою: навіть скромний програміст зазвичай знає, як написати один вкладиш із описом його функцій, а також параметри отримують "автоматичне" документування, і ціле прив'язується до відповідного коду, і таким чином вони уникають документації " дезінсування "та відставання розвитку.
4. Найчастіше створюється форум. Це потужне соціальне медіа, де кінцеві користувачі та програмісти можуть спілкуватися між собою (і між своїми однолітками, можливо, у підфорумах "лише для розробників"). Це дозволяє поступово з'являтися та консолідувати багато знань за допомогою створених спільнотою (читайте: не зважування на команду розробників) FAQ та HOWTO.
5. У дійсно великих проектах також створюється вікі. Я заявляю про "великі проекти", тому що вони часто є тими, хто має достатньо послідовників, щоб створити вікі (дев є), а потім фактично заповнити його поза "голими кістками" (громада робить).

Оглядові документи, такі як ви описуєте, рідкісні навіть у комерційних проектах. Вони вимагають додаткових зусиль з невеликою цінністю для розробників. Також розробники прагнуть не писати документацію, якщо це дійсно не потрібно. У деяких проектах пощастило мати членів, які добре вміють писати техніку, і, як результат, мати гарну документацію для користувачів. Документація для розробників, якщо вона існує, навряд чи буде оновлена, щоб відобразити зміни коду.

Будь-який добре організований проект матиме дерево каталогів, яке є досить зрозумілим. Деякі проекти будуть документувати цю ієрархію та / або причини, які вона була обрана. Багато проектів дотримуються відносно стандартних макетів коду, тому якщо ви розумієте один, ви зрозумієте макет інших проектів, використовуючи той самий макет.

Щоб змінити рядок коду, вам потрібно обмежене розуміння навколишнього коду. Вам ніколи не доведеться розуміти всю базу коду, щоб це зробити. Якщо у вас є розумне уявлення про тип функції, яка порушена, часто можна переміщатися по ієрархії каталогів досить швидко.

Щоб змінити рядок коду, вам потрібно зрозуміти метод, в якому знаходиться рядок. Якщо ви розумієте, яка очікувана поведінка методу, ви повинні мати можливість внести коригувальні зміни або розширення в функціонал.

Для мов, які надають масштабування, ви можете змінити приватні методи масштабування. У цьому випадку вам може знадобитися змінити абонентів, а також метод або методи рефактора. Це вимагає більш широкого, але все ж обмеженого розуміння бази коду.

Дивіться мою статтю Додавання SHA-2 до tinyca для прикладу того, як можна зробити такі зміни. Я дуже розумію код, який використовується для створення інтерфейсу.

Чи є подібні речі, і я їх пропускаю? Речі, які виконують ту саму роботу, як я описав?

Існує чудова книга під назвою «Архітектура додатків з відкритим кодом», яка надає детальний опис різноманітних проектів з відкритим кодом з відкритим кодом. Однак я не впевнений, чи точно він заповнює роль, яку ви собі уявляєте, тому що я вважаю, що її основна аудиторія призначена для розробників, які шукають шаблони, які слід дотримуватися під час створення власних додатків, а не нових учасників проектів, представлених у книзі. (хоча я впевнений, що це може бути корисним там).

Тому що є набагато більше програмістів з відкритим кодом, ніж технічних авторів з відкритим кодом.

Документація потребує обслуговування та часу, щоб бути в курсі. Чим об’ємніша документація, тим більше потрібно. А документація, яка не синхронізована з кодом, гірша за марну: вона вводить в оману та приховує замість того, щоб розкривати.

Добре задокументована база коду краще, ніж одна менш задокументована, але документація може зайняти стільки часу, скільки написання коду в першу чергу. Отже, ваше питання полягає в тому, чи краще мати добре задокументовану базу коду чи кодову базу, яка вдвічі більша? Чи варто оновлювати документацію, коли зміни коду варті внеску додаткових розробників, які він може або не може внести?

Код доставки виграє. Скорочення обсягу зусиль, що вкладаються до речей, крім коду доставки, може змусити кодовувати частіше, і, швидше за все, відправляти її раніше, ніж у неї закінчуються ресурси.

Це не означає, що речі поруч із доставкою мають значення. Документація додає цінність проекту, і при досить великому проекті вартість взаємозв’язку на додавання іншого розробника може бути набагато вище, ніж додавання документатора. І, як зазначалося, документація може збільшити інвестиції в проект (полегшивши приєднання нових програмістів).

Однак нічого не продається як успіх: проект, який не працює або не робить нічого цікавого, рідко також привертає розробників.

Документація бази коду - це форма мета-роботи. Ви можете витратити багато часу на написання вигадливих документів, що описують кодову базу, яка не приносить великої цінності, або ви можете витратити час, роблячи речі, які хочуть споживачі вашої кодової бази, і щоб ваша база коду мала значення.

Іноді ускладнення справи робить тих, хто виконує завдання краще. Або через вищий ступінь прихильності проекту (витрачати години на години, вивчаючи архітектуру), або через упередженість майстерності (якщо ви вже фахівець у галузі відповідних технологій, швидкість швидкість буде швидшою, тому бар'єр відсутній така документація менш важлива: таким чином, більше команди приєднується до команди, а менше початківців).

Нарешті, з причин, зазначених вище, нинішні розробники, ймовірно, будуть експертами по кодовій базі. Написання такої документації не дуже допомагає їм зрозуміти базу коду, оскільки вони вже мають знання, це допомагає лише іншим розробникам. Значна частина розробки з відкритим кодом базується на тому, щоб "почухати свербіж", який має розробник із кодом: відсутність документації, яка вже говорить про те, що розробник знає, рідко свербить.

Окрім додаткових зусиль , деякі проекти з відкритим кодом спеціально калікують свої документації, щоб отримати безкоштовні робочі місця для своїх керівників (щось реалізовувати чи проводити тренінги). Вони не тільки не мають огляду коду, але їх API та підручники є поганими або відсутні багато речей.

Просто назвіть одну досить популярну: bluez. Удачі в пошуку хорошого підручника, окрім того, щоб перевірити наявні пристрої.