Запитання з тегом «documentation»

Багато людей стверджують, що "коментарі повинні пояснювати" чому ", а не" як "". Інші кажуть, що «код повинен бути самодокументованим», а коментарі мають бути мізерними. Роберт К. Мартін стверджує, що (перефразувавши мої власні слова) часто "коментарі - це вибачення за погано написаний код". Моє запитання таке: Що поганого в поясненні …

236 programming-practices  documentation  comments 

Мене спеціально просять дати рядок за рядком (або, якщо це доречно - наприклад, зображення за зображенням тощо) пояснення або коментар, який мій начальник хоче прочитати та дотримуватися. Оскільки він не програміст, він не може слідувати коду, тому хоче, щоб це все було перекладено англійською. Хтось раніше просив це зробити? Я …

155 documentation 

Стандарт RFC 2606 резервує доменні імена example.org , example.net та example.com для використання в якості прикладів у документації. Що таке еквівалент для телефонного номера (включаючи код країни), який може бути використаний як приклад, наприклад, для надання користувачам прикладу в якому форматі для введення телефонних номерів? У кращому випадку це макетний …

112 documentation  standards  help-documentation 

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

104 documentation  large-scale-project 

Під час зустрічі з приводу відката стороннього SDK від останньої версії було відмічено, що наші розробники вже позначили в історії фіксації, що останню версію не слід використовувати. Деякі розробники стверджували, що це була погана практика, і натомість це слід було зазначити або у вихідному файлі (тобто // Don't upgrade SDK …

94 version-control  documentation 

Я працюю над досить великим проектом і отримав завдання зробити кілька перекладів для нього. Було багато ярликів, які не були перекладені, і, коли я копав код, я знайшов цей маленький шматочок коду //TODO translations Це змусило мене задуматися про сенс цих коментарів до себе (та інших?), Тому що у мене …

86 documentation  comments 

Я написав наступний код: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Тут є коментований рядок. Але я думаю, що це робить код більш зрозумілим, роблячи очевидним, …

83 documentation  comments 

Перш за все, у цьому питанні я хотів би триматися осторонь полеміки щодо того, добре чи погано коментує джерело. Я просто намагаюся зрозуміти більш чітко, що означають люди, коли вони говорять про коментарі, які говорять ЧОМУ, ЩО чи ЯК. Ми часто бачимо вказівки на кшталт "Коментарі повинні говорити, ЧОМУ; сам …

78 documentation  comments 

Я працював над проектом три місяці тому, а потім раптом з’явився ще один невідкладний проект, і мене попросили перенести свою увагу. З завтрашнього дня я повернуся до старого проекту. Я усвідомлюю, що не пам’ятаю, що саме робив. Я не знаю, з чого почати. Як я можу задокументувати проект таким чином, …

72 project-management  documentation 

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

66 career-development  documentation 

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

63 programming-practices  code-quality  documentation 

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

60 documentation  automation  automatic-programming 

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

59 documentation  component  jargon 

Іноді я опиняюся в ситуаціях, коли частина коду, яку я пишу, є (або, здається, такою ) само собою зрозумілою, що її назва в основному повториться як коментар: class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; set; }; } (C # …

54 programming-practices  documentation  language-agnostic 

Коли ви використовуєте такі інструменти, як jsdocs , він генерує статичні файли HTML та його стилі у вашій кодовій базі на основі коментарів у вашому коді. Чи слід перевіряти ці файли у сховищі Git чи їх слід ігнорувати .gitignore?

49 git  documentation