Плохая и хорошая документация языка

Язык Go не отличается красотой. Кто-то называет его «намеренно простым», кто-то уродливым. Но с чем у Go действительно всё классно — так это с документацией. Там много хорошего, но вот главное, на мой взгляд:

  1. A Tour of Go — интерактивное введение в язык.
  2. Effective Go — книга о том, как писать идиоматичный код на Go.
  3. Ссылки из документации на исходники каждой функции стандартной библиотеки (например, Max).

Для сравнения я взял топ-10 языков из StackOverflow Developer Survey и посмотрел, как у них дела с этими тремя пунктами.

Топ-10 языков
Рейтинг популярных языков по версии StackOverflow

1. JavaScript

У языка даже своего сайта нет ツ Есть миллион обучалок, но единого авторитетного источника — нет. Документация по языку есть только благодаря Мозилле. Ссылок на исходники нет, конечно. Зато по каждой функции есть интерактивный пример, это отлично.

2. SQL

Всё как у JS, только хуже — в мире SQL не нашлось своей Мозиллы, которая бы сделала документацию с примерами. Где свой SQL получали, там и ищите.

Кстати, если вы уже знаете основы SQL и хотите прокачать понимание индексов, оптимизацию запросов и всякое такое — посмотрите онлайн-книгу Use The Index, Luke, она хороша.

3. Python

Первый язык в топе с собственным сайтом. Есть ссылка Get Started, но дальше разбегаются глаза — что выбрать? Вместо рекомендованной авторами базовой обучалки вываливают на новичка простыню ссылок. Официальный туториал найти можно только каким-то нетривиальным способом. Интерактива нет. Незачёт.

Исходников отдельных функций нет, исходники модулей — только если они написаны на Python (например, для heapq исходники есть, а для itertools — нет).

4. Java

Язык принадлежит компании Оракл, этим всё сказано. Заходите на официальный сайт посмеяться.

Сайт Java
Это весь сайт. Вот прям совсем весь. Учитесь!

Если пройтись по ссылкам дальше, попадаешь на страницу Learn Java Skills, где Оракл любезно предложит прикупить семинар. Если ну очень постараться, можно набрести на документацию по языку, даже с примерами. Странно, что за доступ не надо платить или хотя бы регистрироваться в Oracle Developer Network — надеюсь, эту недоработку скоро исправят.

5. Bash

Не ожидал, но у него есть сайт и документация. Спасибо и на том.

6. С#

Первый язык родом из нового тысячелетия в списке. Есть интерактивный туториал, тур по языку и руководство разработчика. Неплохо! В документации есть интерактивные примеры, а вот ссылок на исходники нет.

7. PHP

Первое, что встречает на официальном сайте — Please DO NOT use this version in production, it is an early test version. Спасибо, да. Я бы вообще сделал DO NOT use this in production официальным слоганом языка. Кхм, пардон, отвлёкся. Есть неинтерактивная обучалка, неплохая документация со статическими примерами и комментариями сообщества, и, неожиданно — аж целая книга PHP at the Core: A Hacker's Guide.

Сайт Java
Some leaks are unavoidable, объясняют нам знатоки PHP.

8. TypeScript

Новейший язык, 2012 года выпуска. Несколько введений, местами интерактивные. Подробный учебник, который начинается как интерактивный, но быстро превращается в статический (как так?). Ссылок на исходники нет, но они особо и не нужны — у тайп-скрипта нет собственной стандартной библиотеки.

9. C++

Есть интерактивный тур по языку! Шучу, конечно. Тур выложен в PDF, что тут скажешь. Зато есть Core Guidelines о том, как писать правильный код.

10. C

Сайта нет, ничего нет, населена роботами.

⌘ ⌘ ⌘

Счёт 10-0 в пользу Go.

Заметка из телеграм-канала «Thank Go»