Как правильно откоментировать этот код?

Помогите пожалуйста грамотна откомментировать код

import xml.etree.ElementTree as XmlElementTree
import xml.etree.ElementTree as XmlElementTree
import httplib2
import uuid
#импорт нативных библиотек
from config import ***
#импорт конфига

***_HOST = '***'
***_PATH = '/***_xml'
CHUNK_SIZE = 1024 ** 2
#?

def speech_to_text(
   filename=None, 
   bytes=None, 
   request_id=uuid.uuid4().hex, 
   topic='notes',  
   lang='ru-RU',
   key=***_API_KEY):

   if filename:
   with open(filename, 'br') as file:
   bytes = file.read()
   if not bytes:
   raise Exception('Neither file name nor bytes provided.')


   bytes = convert_to_pcm16b16000r(in_bytes=bytes)


   url = ***_PATH + '?uuid=%s&key=%s&topic=%s&lang=%s' % (
   request_id,
   key,
   topic,
   lang
   )
   #метод обработки файла

   chunks = read_chunks(CHUNK_SIZE, bytes)


   connection = httplib2.HTTPConnectionWithTimeout(***_HOST)
   #подключение к страницы для передачи заголовка
   connection.connect()
   connection.putrequest('POST', url)
   connection.putheader('Transfer-Encoding', 'chunked')
   connection.putheader('Content-Type', 'audio/x-pcm;bit=16;rate=16000')
   connection.endheaders()


   for chunk in chunks:
   connection.send(('%s\r\n' % hex(len(chunk))[2:]).encode())
   connection.send(chunk)
   connection.send('\r\n'.encode())

   connection.send('0\r\n\r\n'.encode())
   response = connection.getresponse()
   #отправка и получение ответа

   if response.code == 200:
   response_text = response.read()
   xml = XmlElementTree.fromstring(response_text)
   #?
   if int(xml.attrib['success']) == 1:
   max_confidence = - float("inf")
   text = ''

   for child in xml:
   if float(child.attrib['confidence']) > max_confidence:
   text = child.text
   max_confidence = float(child.attrib['confidence'])

   if max_confidence != - float("inf"):
   return text
   else:

   raise SpeechException('No text found.\n\nResponse:\n%s' % (response_text))
   else:
   raise SpeechException('No text found.\n\nResponse:\n%s' % (response_text))
   else:
   raise SpeechException('Unknown error.\nCode: %s\n\n%s' % (response.code, response.read()))

   сlass SpeechException(Exception):
   pass

Ответы (1 шт):

Автор решения: Roman Konoval

У вашего кода будет как минимум две категории пользователей:

  1. клиенты, которым все равно, что там внутри. Главное для них - знать как пользоваться этим API.
  2. программисты, которые будут поддерживать (и развивать) этот код.

Клиенты

В идеале для них важны ответы на такие вопросы:

  1. что эта функция делает?
  2. примеры использования
  3. какие параметры принимает?
  4. в каком формате должны быть параметры? Скажем, у аудио 100500 форматов, какие поддерживаются?
  5. какие ошибочные ситуации функции определяет? как на них реагирует?
  6. конфигурация: ключи, хосты, пароли - это от какого стороннего сервиса? Где из взять?

Тут docstring, который отвечает на эти вопросы был бы очень полезен.

Программисты

Их (в дополнение к вышеперечисленному) интересует:

  1. как функция устроена?
  2. как ее протестировать?
  3. как ее уже тестировали?

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

→ Ссылка